@silo-ai/silo 0.1.1 → 0.1.2

package/README.md

@@ -47,6 +47,12 @@ The first schema mutation creates the database. Inspect the resulting logical sc
 
 Run `silo --help` and `silo <group> <command> --help` for the authoritative command syntax and examples. The self-contained [`skills/silo/`](skills/silo/) package includes both agent operating practices and the exact JSON request contracts it references.
 
+To make the packaged guidance discoverable without installing a separate agent skill, add this rule to your global `AGENTS.md`:
+
+> - When told to “use Silo” or do something with Silo, run `silo skill` and follow its instructions. Read any referenced task guide or JSON Schema with `silo skill <relative-path>`.
+
+`silo skill` prints the main skill. Its relative links can be read from any directory, for example with `silo skill tasks/create-table.md` or `silo skill schemas/row-write.schema.json`.
+
 ## Import a schema template
 
 Import the bundled agent-first task schema into the current repository:

package/dist/bin.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { binary, command, number, option, optional, positional, runSafely, string, subcommands } from "cmd-ts";
+import { binary, command, extendType, flag, number, oneOf, option, optional, positional, runSafely, string, subcommands } from "cmd-ts";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { File } from "cmd-ts/dist/cjs/batteries/fs.js";
 import { DatabaseSync, backup, constants } from "node:sqlite";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { isIP } from "node:net";
 import { execFile, execFileSync, spawn } from "node:child_process";
@@ -15,7 +15,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { DeleteObjectsCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 import { promisify } from "node:util";
 //#region src/model.ts
 var SiloError = class extends Error {
@@ -1306,6 +1306,10 @@ var SiloDatabase = class SiloDatabase {
 			canonical.close();
 		}
 	}
+	async backupRecovery(path) {
+		this.database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+		await backup(this.database, path);
+	}
 	rebasePending(pending, generation, etag, discardTransactionId) {
 		if (!this.getSyncState()) throw new SiloError(exits.integrity, "sync_metadata_missing", "Restored sync metadata is missing.");
 		try {
@@ -2231,6 +2235,63 @@ var S3SyncRemote = class {
 	generationUrl(generation) {
 		return `s3://${this.bucket}/${this.prefix}/generations/${generation}`;
 	}
+	async listGenerations() {
+		const prefix = `${this.prefix}/generations/`;
+		const generations = /* @__PURE__ */ new Map();
+		let continuationToken;
+		try {
+			do {
+				const response = await this.client.send(new ListObjectsV2Command({
+					Bucket: this.bucket,
+					Prefix: prefix,
+					ContinuationToken: continuationToken
+				}));
+				for (const object of response.Contents ?? []) {
+					const generation = (object.Key?.slice(prefix.length))?.split("/", 1)[0];
+					if (!generation || !object.LastModified) continue;
+					const previous = generations.get(generation);
+					if (!previous || object.LastModified > previous) generations.set(generation, object.LastModified);
+				}
+				continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+			} while (continuationToken);
+			return [...generations].map(([generation, last_modified]) => ({
+				generation,
+				last_modified
+			}));
+		} catch (error) {
+			throw new SiloError(exits.io, "sync_generations_list_failed", error instanceof Error ? error.message : String(error));
+		}
+	}
+	async deleteGeneration(generation) {
+		const prefix = `${this.prefix}/generations/${generation}/`;
+		const objects = [];
+		let continuationToken;
+		try {
+			do {
+				const response = await this.client.send(new ListObjectsV2Command({
+					Bucket: this.bucket,
+					Prefix: prefix,
+					ContinuationToken: continuationToken
+				}));
+				objects.push(...(response.Contents ?? []).flatMap((object) => object.Key ? [{ Key: object.Key }] : []));
+				continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+			} while (continuationToken);
+			for (let offset = 0; offset < objects.length; offset += 1e3) {
+				const batch = objects.slice(offset, offset + 1e3);
+				const result = await this.client.send(new DeleteObjectsCommand({
+					Bucket: this.bucket,
+					Delete: {
+						Objects: batch,
+						Quiet: true
+					}
+				}));
+				if (result.Errors?.length) throw new Error(result.Errors.map((item) => `${item.Key ?? "unknown key"}: ${item.Message ?? item.Code ?? "delete failed"}`).join("; "));
+			}
+			return objects.length;
+		} catch (error) {
+			throw new SiloError(exits.io, "sync_generation_delete_failed", `Generation ${generation}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
 };
 var LitestreamCheckpoint = class {
 	executable;
@@ -2384,7 +2445,7 @@ var SiloSync = class {
 				const database = SiloDatabase.open(this.workspace, true, true);
 				try {
 					const state = database.getSyncState();
-					if (head && !state) throw new SiloError(exits.revision, "sync_local_diverged", "A remote database already exists; initialize from a workspace without local state.");
+					if (head && !state) throw new SiloError(exits.revision, "sync_local_diverged", `A local database and remote generation ${head.manifest.generation} both exist. Choose an explicit sync recovery workflow.`);
 					const configured = database.configureSync(remoteUrl, head?.manifest.database_id);
 					if (head) validateHead(this.workspace, head, configured.database_id);
 				} finally {
@@ -2394,6 +2455,88 @@ var SiloSync = class {
 			return this.status();
 		});
 	}
+	async adoptRemote(remoteUrl, confirmedGeneration) {
+		return withSyncLock(this.workspace, async () => {
+			await this.services.checkpoint.check();
+			if (!existsSync(this.workspace.databasePath)) throw new SiloError(exits.absent, "sync_local_absent", "A local database is required to use the adopt-remote recovery workflow.");
+			const local = SiloDatabase.open(this.workspace, true, true);
+			try {
+				if (local.getSyncState()) throw new SiloError(exits.workspace, "sync_already_configured", "The local database is already configured for synchronization.");
+			} finally {
+				local.close();
+			}
+			const remote = this.services.remote(remoteUrl);
+			const head = await remote.readHead();
+			if (!head) throw new SiloError(exits.absent, "sync_remote_absent", "Remote HEAD does not exist.");
+			validateHead(this.workspace, head);
+			this.confirmRecovery(head, confirmedGeneration);
+			const restored = temporaryPath(this.workspace, "adopt");
+			const preserved = `${this.workspace.databasePath}.recovery-local-${randomUUID()}.sqlite`;
+			try {
+				await this.restoreAndVerify(remote, head, restored);
+				const original = SiloDatabase.open(this.workspace, true, true);
+				try {
+					await original.backupRecovery(preserved);
+				} finally {
+					original.close();
+				}
+				installDatabase(restored, this.workspace.databasePath);
+				const adopted = SiloDatabase.open(this.workspace, true, true);
+				try {
+					adopted.markSynchronized(head.manifest.generation, head.etag);
+				} finally {
+					adopted.close();
+				}
+			} finally {
+				removeDatabase(restored);
+			}
+			return {
+				status: await this.status(),
+				preserved
+			};
+		});
+	}
+	async replaceRemote(remoteUrl, confirmedGeneration) {
+		return withSyncLock(this.workspace, async () => {
+			await this.services.checkpoint.check();
+			if (!existsSync(this.workspace.databasePath)) throw new SiloError(exits.absent, "sync_local_absent", "A local database is required to use the replace-remote recovery workflow.");
+			const remote = this.services.remote(remoteUrl);
+			const head = await remote.readHead();
+			if (!head) throw new SiloError(exits.absent, "sync_remote_absent", "Remote HEAD does not exist.");
+			validateHead(this.workspace, head);
+			this.confirmRecovery(head, confirmedGeneration);
+			const candidate = temporaryPath(this.workspace, "replace");
+			const local = SiloDatabase.open(this.workspace, true, true);
+			try {
+				if (local.getSyncState()) throw new SiloError(exits.workspace, "sync_already_configured", "The local database is already configured for synchronization.");
+				await local.backupRecovery(candidate);
+			} finally {
+				local.close();
+			}
+			try {
+				const configured = SiloDatabase.open({
+					...this.workspace,
+					databasePath: candidate
+				}, true, true);
+				try {
+					configured.configureSync(remoteUrl, head.manifest.database_id);
+				} finally {
+					configured.close();
+				}
+				await this.publishDatabase(candidate, remote, head);
+				installDatabase(candidate, this.workspace.databasePath);
+			} finally {
+				removeDatabase(candidate);
+			}
+			return {
+				status: await this.status(),
+				preserved: remote.generationUrl(head.manifest.generation)
+			};
+		});
+	}
+	confirmRecovery(head, confirmedGeneration) {
+		if (confirmedGeneration !== head.manifest.generation) throw new SiloError(exits.revision, "sync_recovery_confirmation_mismatch", `Confirmation must equal current remote generation ${head.manifest.generation}.`);
+	}
 	async status() {
 		if (!existsSync(this.workspace.databasePath)) return {
 			state: "unconfigured",
@@ -2501,7 +2644,7 @@ var SiloSync = class {
 	async push() {
 		return withSyncLock(this.workspace, async () => {
 			await this.services.checkpoint.check();
-			let database = SiloDatabase.open(this.workspace, true, true);
+			const database = SiloDatabase.open(this.workspace, true, true);
 			let state;
 			let pendingCount;
 			try {
@@ -2527,64 +2670,111 @@ var SiloSync = class {
 				head = await remote.readHead();
 				if (head) validateHead(this.workspace, head, state.database_id);
 			}
-			database = SiloDatabase.open(this.workspace, true, true);
-			const publicationId = randomUUID();
-			const generation = randomUUID();
-			const candidate = temporaryPath(this.workspace, "publish");
-			const verified = temporaryPath(this.workspace, "verify");
+			await this.publishDatabase(this.workspace.databasePath, remote, head);
+			return this.status();
+		});
+	}
+	async prune(olderThanDays = 7, apply = false, now = /* @__PURE__ */ new Date()) {
+		return withSyncLock(this.workspace, async () => {
+			const database = SiloDatabase.open(this.workspace);
+			let state;
 			try {
-				await database.backupCanonical(candidate, generation);
-				const manifest = {
-					format_version: 1,
-					database_id: state.database_id,
-					identity: this.workspace.identity,
-					generation,
-					publication_id: publicationId,
-					parent_generation: head?.manifest.generation ?? null,
-					schema_revision: database.getSchema().revision,
-					database_sha256: hashDatabase(candidate),
-					created_at: (/* @__PURE__ */ new Date()).toISOString()
-				};
-				database.close();
-				await this.services.checkpoint.publish(candidate, remote.generationUrl(generation));
-				await this.services.checkpoint.restore(remote.generationUrl(generation), verified);
-				if (hashDatabase(verified) !== manifest.database_sha256) throw new SiloError(exits.integrity, "sync_checkpoint_hash_mismatch", "The restored checkpoint does not match the published database.");
-				const verification = SiloDatabase.open({
-					...this.workspace,
-					databasePath: verified
-				}, false, true);
-				try {
-					if (verification.getSchema().revision !== manifest.schema_revision) throw new SiloError(exits.integrity, "sync_checkpoint_schema_mismatch", "The published checkpoint schema does not match its manifest.");
-					const integrity = verification.query("PRAGMA integrity_check");
-					if (integrity.rows.length !== 1 || integrity.rows[0]?.[0] !== "ok") throw new SiloError(exits.integrity, "integrity_check_failed", "The published checkpoint failed SQLite integrity checking.");
-				} finally {
-					verification.close();
-				}
-				let etag;
-				try {
-					etag = await remote.publishHead(manifest, head?.etag ?? null);
-				} catch (error) {
-					if (!(error instanceof SiloError) || error.code !== "sync_head_changed") throw error;
-					const current = await remote.readHead();
-					if (!current || current.manifest.publication_id !== publicationId) throw error;
-					etag = current.etag;
-				}
-				const updated = SiloDatabase.open(this.workspace, true, true);
-				try {
-					updated.markSynchronized(generation, etag);
-				} finally {
-					updated.close();
-				}
+				state = database.getSyncState();
 			} finally {
-				try {
-					database.close();
-				} catch {}
-				removeDatabase(candidate);
-				removeDatabase(verified);
+				database.close();
 			}
-			return this.status();
+			if (!state) throw new SiloError(exits.workspace, "sync_not_configured", "Synchronization is not configured.");
+			const remote = this.services.remote(state.remote_url);
+			const head = await remote.readHead();
+			if (!head) throw new SiloError(exits.absent, "sync_remote_absent", "Remote HEAD does not exist.");
+			validateHead(this.workspace, head, state.database_id);
+			const cutoff = /* @__PURE__ */ new Date(now.getTime() - olderThanDays * 864e5);
+			const generations = await remote.listGenerations();
+			const eligible = generations.filter((item) => item.generation !== head.manifest.generation && item.last_modified.getTime() <= cutoff.getTime()).map((item) => item.generation).sort();
+			const deleted = [];
+			if (apply && eligible.length) for (const generation of eligible) {
+				const current = await remote.readHead();
+				if (!current || current.etag !== head.etag) throw new SiloError(exits.revision, "sync_head_changed", deleted.length ? `Remote HEAD changed during cleanup after ${deleted.length} generation(s) were deleted; remaining generations were preserved.` : "Remote HEAD changed during cleanup; no generations were deleted.");
+				validateHead(this.workspace, current, state.database_id);
+				if (generation === current.manifest.generation) continue;
+				await remote.deleteGeneration(generation);
+				deleted.push(generation);
+			}
+			return {
+				remote_url: state.remote_url,
+				current_generation: head.manifest.generation,
+				cutoff: cutoff.toISOString(),
+				scanned_generations: generations.length,
+				eligible_generations: eligible,
+				deleted_generations: deleted,
+				dry_run: !apply
+			};
 		});
 	}
+	async publishDatabase(databasePath, remote, head) {
+		let database = SiloDatabase.open({
+			...this.workspace,
+			databasePath
+		}, true, true);
+		const state = database.getSyncState();
+		const publicationId = randomUUID();
+		const generation = randomUUID();
+		const candidate = temporaryPath(this.workspace, "publish");
+		const verified = temporaryPath(this.workspace, "verify");
+		try {
+			await database.backupCanonical(candidate, generation);
+			const manifest = {
+				format_version: 1,
+				database_id: state.database_id,
+				identity: this.workspace.identity,
+				generation,
+				publication_id: publicationId,
+				parent_generation: head?.manifest.generation ?? null,
+				schema_revision: database.getSchema().revision,
+				database_sha256: hashDatabase(candidate),
+				created_at: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			database.close();
+			await this.services.checkpoint.publish(candidate, remote.generationUrl(generation));
+			await this.services.checkpoint.restore(remote.generationUrl(generation), verified);
+			if (hashDatabase(verified) !== manifest.database_sha256) throw new SiloError(exits.integrity, "sync_checkpoint_hash_mismatch", "The restored checkpoint does not match the published database.");
+			const verification = SiloDatabase.open({
+				...this.workspace,
+				databasePath: verified
+			}, false, true);
+			try {
+				if (verification.getSchema().revision !== manifest.schema_revision) throw new SiloError(exits.integrity, "sync_checkpoint_schema_mismatch", "The published checkpoint schema does not match its manifest.");
+				const integrity = verification.query("PRAGMA integrity_check");
+				if (integrity.rows.length !== 1 || integrity.rows[0]?.[0] !== "ok") throw new SiloError(exits.integrity, "integrity_check_failed", "The published checkpoint failed SQLite integrity checking.");
+			} finally {
+				verification.close();
+			}
+			let etag;
+			try {
+				etag = await remote.publishHead(manifest, head?.etag ?? null);
+			} catch (error) {
+				if (!(error instanceof SiloError) || error.code !== "sync_head_changed") throw error;
+				const current = await remote.readHead();
+				if (!current || current.manifest.publication_id !== publicationId) throw error;
+				etag = current.etag;
+			}
+			const updated = SiloDatabase.open({
+				...this.workspace,
+				databasePath
+			}, true, true);
+			try {
+				updated.markSynchronized(generation, etag);
+			} finally {
+				updated.close();
+			}
+		} finally {
+			try {
+				database.close();
+			} catch {}
+			removeDatabase(candidate);
+			removeDatabase(verified);
+		}
+	}
 	async restoreAndVerify(remote, head, outputPath) {
 		await this.services.checkpoint.restore(remote.generationUrl(head.manifest.generation), outputPath);
 		if (hashDatabase(outputPath) !== head.manifest.database_sha256) throw new SiloError(exits.integrity, "sync_checkpoint_hash_mismatch", "The restored checkpoint does not match remote HEAD.");
@@ -2605,6 +2795,23 @@ var SiloSync = class {
 };
 //#endregion
 //#region src/cli.ts
+const skillResources = [
+	"SKILL.md",
+	"tasks/alter-table.md",
+	"tasks/create-report.md",
+	"tasks/create-table.md",
+	"tasks/query-with-sql.md",
+	"tasks/synchronize.md",
+	"tasks/update-with-revision.md",
+	"tasks/upsert-rows.md",
+	"schemas/report-put.schema.json",
+	"schemas/row-write.schema.json",
+	"schemas/table-alter.schema.json",
+	"schemas/table-create.schema.json"
+];
+function readSkillResource(resource = "SKILL.md") {
+	return readFileSync(fileURLToPath(new URL(`../skills/silo/${resource}`, import.meta.url)), "utf8");
+}
 const inputFile = option({
 	type: optional(File),
 	long: "file",
@@ -2753,6 +2960,16 @@ const status = command({
 		])));
 	})
 });
+const skill = command({
+	name: "skill",
+	description: "Print the packaged Silo agent skill or one of its referenced resources.",
+	args: { resource: positional({
+		type: optional(oneOf(skillResources)),
+		displayName: "relative-path",
+		description: "A task or schema path referenced by SKILL.md."
+	}) },
+	handler: ({ resource }) => output(readSkillResource(resource))
+});
 const databaseList = command({
 	name: "list",
 	description: "Discover Silo databases in the application-data catalog.",
@@ -3223,6 +3440,36 @@ const syncInit = command({
 		output(renderSyncStatus(await new SiloSync(resolveWorkspace()).initialize(remote)));
 	})
 });
+function renderSyncRecovery(result) {
+	return `${renderSyncStatus(result.status)}\n\n${heading("Preserved losing copy", `\`${result.preserved}\``)}`;
+}
+const recoveryArgs = {
+	remote: positional({
+		type: string,
+		displayName: "s3-url"
+	}),
+	confirm: option({
+		type: string,
+		long: "confirm",
+		description: "Confirm the exact current remote generation that this recovery will resolve."
+	})
+};
+const syncAdoptRemote = command({
+	name: "adopt-remote",
+	description: "Replace an unconfigured local database after preserving it as a recovery snapshot.",
+	args: recoveryArgs,
+	handler: withErrors(async ({ remote, confirm }) => {
+		output(renderSyncRecovery(await new SiloSync(resolveWorkspace()).adoptRemote(remote, confirm)));
+	})
+});
+const syncReplaceRemote = command({
+	name: "replace-remote",
+	description: "Publish an unconfigured local database over a confirmed remote generation.",
+	args: recoveryArgs,
+	handler: withErrors(async ({ remote, confirm }) => {
+		output(renderSyncRecovery(await new SiloSync(resolveWorkspace()).replaceRemote(remote, confirm)));
+	})
+});
 const syncStatus = command({
 	name: "status",
 	description: "Compare local synchronization state with remote HEAD.",
@@ -3250,6 +3497,24 @@ const pull = command({
 		output(renderSyncStatus(await new SiloSync(resolveWorkspace()).pull()));
 	})
 });
+const push = command({
+	name: "push",
+	description: "Publish a merged immutable checkpoint and conditionally advance remote HEAD.",
+	args: {},
+	handler: withErrors(async () => {
+		output(renderSyncStatus(await new SiloSync(resolveWorkspace()).push()));
+	})
+});
+function renderPruneResult(result) {
+	return heading(result.dry_run ? "Synchronization Cleanup Preview" : "Synchronization Cleanup", table(["Property", "Value"], [
+		["Remote", result.remote_url],
+		["Current generation", result.current_generation],
+		["Cutoff", result.cutoff],
+		["Scanned generations", result.scanned_generations],
+		["Eligible generations", result.eligible_generations.length],
+		["Deleted generations", result.deleted_generations.length]
+	]) + (result.eligible_generations.length ? `\n\n${heading("Eligible Generation IDs", result.eligible_generations.map((id) => `- \`${id}\``).join("\n"))}` : ""));
+}
 //#endregion
 //#region src/bin.ts
 const result = await runSafely(binary(subcommands({
@@ -3257,21 +3522,43 @@ const result = await runSafely(binary(subcommands({
 	version: "0.1.0",
 	cmds: {
 		status,
-		push: command({
-			name: "push",
-			description: "Publish a merged immutable checkpoint and conditionally advance remote HEAD.",
-			args: {},
-			handler: withErrors(async () => {
-				output(renderSyncStatus(await new SiloSync(resolveWorkspace()).push()));
-			})
-		}),
+		skill,
+		push,
 		pull,
 		sync: subcommands({
 			name: "sync",
 			cmds: {
 				init: syncInit,
+				"adopt-remote": syncAdoptRemote,
+				"replace-remote": syncReplaceRemote,
 				status: syncStatus,
-				discard: syncDiscard
+				discard: syncDiscard,
+				prune: command({
+					name: "prune",
+					description: "Preview or delete remote generations older than a grace period.",
+					args: {
+						olderThan: option({
+							type: extendType(number, {
+								displayName: "days",
+								async from(value) {
+									if (!Number.isFinite(value) || value <= 0) throw new Error("Expected a positive number of days.");
+									return value;
+								}
+							}),
+							long: "older-than",
+							description: "Only consider generations at least this many days old.",
+							defaultValue: () => 7
+						}),
+						apply: flag({
+							long: "apply",
+							description: "Delete eligible generations after revalidating remote HEAD.",
+							defaultValue: () => false
+						})
+					},
+					handler: withErrors(async ({ olderThan, apply }) => {
+						output(renderPruneResult(await new SiloSync(resolveWorkspace()).prune(olderThan, apply)));
+					})
+				})
 			}
 		}),
 		database: subcommands({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silo-ai/silo",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT OR Apache-2.0",
   "author": "Alec Larson",
   "repository": {

package/skills/silo/tasks/synchronize.md

@@ -13,6 +13,18 @@ silo sync status
 
 An existing local database with an empty remote becomes `ahead`; push it to establish remote `HEAD`. An absent local database restores an existing remote. Do not attempt to combine an existing unconfigured local database with an existing remote.
 
+When both sides exist, initialization reports the current remote generation and stops. Inspect the local database, deliberately choose one authority, and confirm that exact remote generation:
+
+```sh
+# Preserve local as a recovery snapshot, then install remote.
+silo sync adopt-remote s3://my-bucket/silo/project --confirm <remote-generation>
+
+# Preserve the old immutable remote generation, then publish local.
+silo sync replace-remote s3://my-bucket/silo/project --confirm <remote-generation>
+```
+
+Both commands report the losing copy's location. A changed confirmation is a new decision point, not permission to retry blindly.
+
 For normal shared work:
 
 ```sh
@@ -31,4 +43,11 @@ Discard rebuilds from remote and replays the remaining pending transactions; it
 
 Schema commands require `clean` status and no pending data transaction. Pull first, make one schema mutation, and push it before further work. Concurrent schema changes do not merge; discard the losing schema transaction, adopt the remote winner, and reapply a compatible change deliberately.
 
-Synchronization is explicit. There is no background replication, Git-style history, automatic conflict winner, or automatic remote generation cleanup.
+Synchronization is explicit. There is no background replication, Git-style history, automatic conflict winner, or background remote generation cleanup. Operators can preview generations older than the default seven-day grace period, then deliberately apply the reviewed cleanup:
+
+```sh
+silo sync prune
+silo sync prune --apply
+```
+
+Use `--older-than <days>` for a longer retention boundary. Never bypass the preview or remove the generation named by remote `HEAD` directly.