knodin 0.13.0 → 0.13.1

package/dist/bin/cli.js

@@ -31,6 +31,7 @@ import { exportContext, grepPackedArtifact, readPackedArtifact } from "../src/co
 import { clearDiagnostics, collectDiagnostics, diagnosticsStatus, disableDiagnostics, enableDiagnostics, inspectDiagnosticsBundle, persistDiagnosticsPreview, recordDiagnosticFailure, } from "../src/diagnostics.js";
 import { getDocSection, listDocTopics } from "../src/docs-sections.js";
 import { diagnoseInstallation } from "../src/doctor.js";
+import { sweepAbandonedCandidates } from "../src/engine/candidate-database.js";
 import { createEngine, describeThrown, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
 import { runSeal } from "../src/engine/seal-command.js";
 import { runSealedQuery } from "../src/engine/sealed-query.js";
@@ -60,6 +61,8 @@ import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, i
 import { applyResponseBudget } from "../src/response-budget.js";
 import { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.js";
 import { inspectKnodinSkills, installKnodinSkills, KNODIN_SKILLS, removeKnodinSkills, } from "../src/skill-management.js";
+import { inventoryStorage } from "../src/storage-inventory.js";
+import { configureStoragePolicy, postOperationStorageMaintenance, resolveStoragePolicy, } from "../src/storage-management.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
 import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, planSystemUnlink, planSystemUnrelate, } from "../src/system-management.js";
 import { coordinationStatus } from "../src/update-coordination.js";
@@ -1289,6 +1292,8 @@ async function main() {
         const depth = invocation.options.depth;
         const retentionDays = invocation.options.retentionDays;
         const keepNewest = invocation.options.keepNewest;
+        const maxCount = invocation.options.maxCount;
+        const maxAllocatedBytes = invocation.options.maxBytes;
         let output;
         if (action === "list")
             output = listBackups(defaultRoots(), { depth });
@@ -1297,16 +1302,70 @@ async function main() {
                 depth,
                 retentionDays,
                 keepNewest,
+                maxCount,
+                maxAllocatedBytes,
                 apply: invocation.options.apply === true,
             });
         }
+        else if (action === "policy") {
+            output = defaultRoots().map((repository) => {
+                if (retentionAction === "status")
+                    return {
+                        repository,
+                        policy: resolveStoragePolicy(repository),
+                        inventory: inventoryStorage(repository),
+                    };
+                if (retentionAction !== "preview" && retentionAction !== "apply")
+                    throw new Error("knodin backups policy requires preview, apply, or status");
+                const changes = {
+                    apply: retentionAction === "apply",
+                };
+                if (maxCount !== undefined)
+                    changes.maxCount = maxCount;
+                if (maxAllocatedBytes !== undefined)
+                    changes.maxAllocatedBytes = maxAllocatedBytes;
+                if (invocation.options.reserveBytes !== undefined)
+                    changes.minFreeBytes = invocation.options.reserveBytes;
+                const mode = invocation.options.mode;
+                if (mode !== undefined) {
+                    changes.enabled = mode !== "disabled";
+                    changes.dryRun = mode === "preview";
+                }
+                const configured = configureStoragePolicy(repository, changes);
+                const maintenance = retentionAction === "apply" ? postOperationStorageMaintenance(repository) : null;
+                const candidateWarnings = [];
+                const candidatesRemoved = maintenance?.policy?.enabled && !maintenance.policy.dryRun
+                    ? sweepAbandonedCandidates(repository, {
+                        onDiagnostic: (warning) => {
+                            if (candidateWarnings.length < 8)
+                                candidateWarnings.push(warning.reason.slice(0, 512));
+                        },
+                    })
+                    : 0;
+                return {
+                    repository,
+                    ...configured,
+                    inventory: inventoryStorage(repository),
+                    cleanup: retentionAction === "apply"
+                        ? { ...maintenance, candidatesRemoved, candidateWarnings }
+                        : pruneBackups([repository], {
+                            ...configured.policy,
+                            depth: 0,
+                            includeRegistry: false,
+                            apply: false,
+                        }),
+                };
+            });
+        }
         else if (action === "retention" && retentionAction === "install") {
             output = installBackupRetention(roots, {
                 depth,
                 retentionDays,
                 keepNewest,
+                maxCount,
+                maxAllocatedBytes,
                 schedule: invocation.options.schedule,
-                dryRun: invocation.options.dryRun === true,
+                dryRun: invocation.options.dryRun,
                 launcher: runtimeCommand,
             });
         }
@@ -1389,10 +1448,19 @@ async function main() {
     const repo = resolved.repo;
     if (cmd !== "doctor") {
         try {
-            maybeRunOpportunisticRetention(repo);
+            const maintenance = maybeRunOpportunisticRetention(repo);
+            const issues = "issues" in maintenance
+                ? maintenance.issues
+                : "result" in maintenance && maintenance.result
+                    ? maintenance.result.skipped.map((entry) => entry.reason)
+                    : [];
+            if (issues?.length)
+                process.stderr.write(`knodin storage: ${issues.slice(0, 8).join("; ").slice(0, 4096)}\n`);
         }
-        catch {
-            // Best-effort cleanup must never make an ordinary command fail.
+        catch (error) {
+            // Cleanup remains nonfatal, but failures are not hidden or reported as
+            // reclaimed storage. Keep stdout/JSON framing untouched.
+            process.stderr.write(`knodin storage: ${String(error).slice(0, 512)}\n`);
         }
     }
     if (cmd === "agent-event" && !fs.existsSync(resolveDbPath(repo)))

package/dist/src/backup-retention.js

@@ -4,7 +4,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import YAML from "yaml";
+import { Database } from "./engine/sqlite.js";
+import { resolveStateDir } from "./engine/state-paths.js";
 import { acquireRepairLease } from "./repair-lease.js";
+import { assertStoragePolicyWritable, MANAGED_BACKUP_DEFAULTS, readLocalStoragePolicy, } from "./storage-policy-contract.js";
+export { MANAGED_BACKUP_DEFAULTS } from "./storage-policy-contract.js";
 const BACKUP = /^db\.sqlite\.backup\.(\d{13})\.([0-9a-f]{8})$/;
 const PRUNED_DIRECTORIES = new Set([
     ".git",
@@ -49,9 +53,30 @@ function registryPaths(configHome) {
         return [];
     }
 }
+/** Shared bounded consent scope; does not scan sibling repositories. */
+export function retentionAppliesToRepository(repository, policy) {
+    let repo;
+    try {
+        repo = fs.realpathSync(repository);
+    }
+    catch {
+        return false;
+    }
+    return policy.roots.some((configuredRoot) => {
+        const root = canonicalDirectory(configuredRoot);
+        if (!root)
+            return false;
+        const relative = path.relative(root, repo);
+        if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`))
+            return false;
+        const segments = relative ? relative.split(path.sep) : [];
+        return (segments.length <= policy.depth &&
+            !segments.some((segment) => PRUNED_DIRECTORIES.has(segment)));
+    });
+}
 function isRepository(candidate) {
     try {
-        const state = fs.lstatSync(path.join(candidate, ".knodin"));
+        const state = fs.lstatSync(resolveStateDir(candidate));
         return state.isDirectory() && !state.isSymbolicLink();
     }
     catch {
@@ -106,12 +131,26 @@ function message(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function inventory(repository) {
-    const stateRoot = path.join(repository, ".knodin");
+    const stateRoot = resolveStateDir(repository);
     const backups = [];
     const skipped = [];
     let entries;
     try {
-        entries = fs.readdirSync(stateRoot, { withFileTypes: true });
+        entries = [];
+        const directory = fs.opendirSync(stateRoot);
+        try {
+            for (let inspected = 0; inspected <= 1024; inspected++) {
+                const entry = directory.readSync();
+                if (!entry)
+                    break;
+                if (inspected === 1024)
+                    throw new Error("backup-inventory-limit-exceeded");
+                entries.push(entry);
+            }
+        }
+        finally {
+            directory.closeSync();
+        }
     }
     catch (error) {
         return { backups, skipped: [{ repository, reason: `inventory-failed: ${message(error)}` }] };
@@ -134,6 +173,11 @@ function inventory(repository) {
                 createdAt: new Date(timestamp).toISOString(),
                 timestamp,
                 bytes: stat.size,
+                allocatedBytes: Number.isSafeInteger(stat.blocks) &&
+                    stat.blocks >= 0 &&
+                    Number.isSafeInteger(stat.blocks * 512)
+                    ? stat.blocks * 512
+                    : null,
                 device: stat.dev,
                 inode: stat.ino,
                 modifiedAtMs: stat.mtimeMs,
@@ -162,11 +206,14 @@ export function listBackups(roots, options = {}) {
         backups,
         count: backups.length,
         totalBytes: backups.reduce((sum, entry) => sum + entry.bytes, 0),
+        totalAllocatedBytes: backups.every((entry) => entry.allocatedBytes !== null)
+            ? backups.reduce((sum, entry) => sum + (entry.allocatedBytes ?? 0), 0)
+            : null,
         skipped,
     };
 }
 function safeLiveDatabase(repository) {
-    const statePath = path.join(repository, ".knodin");
+    const statePath = resolveStateDir(repository);
     const stateStat = fs.lstatSync(statePath);
     if (!stateStat.isDirectory() || stateStat.isSymbolicLink())
         return null;
@@ -199,6 +246,20 @@ function markerExists(target) {
         throw error;
     }
 }
+function recoverableBackup(entry) {
+    let database;
+    try {
+        database = new Database(entry.path, { readonly: true });
+        const result = database.query("PRAGMA quick_check").all();
+        return result.length === 1 && Object.values(result[0] ?? {})[0] === "ok";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        database?.close();
+    }
+}
 export function pruneBackups(roots, options = {}) {
     const now = options.now ?? new Date();
     const retentionDays = options.retentionDays ?? 3;
@@ -207,26 +268,147 @@ export function pruneBackups(roots, options = {}) {
         throw new Error("knodin backups: --retention-days must be an integer from 0 to 3650");
     if (!Number.isInteger(keepNewest) || keepNewest < 0 || keepNewest > 1000)
         throw new Error("knodin backups: --keep-newest must be an integer from 0 to 1000");
+    for (const [name, value] of Object.entries({
+        maxCount: options.maxCount,
+        maxAllocatedBytes: options.maxAllocatedBytes,
+    })) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+            throw new Error(`knodin backups: ${name} must be a non-negative safe integer`);
+    }
     const listed = listBackups(roots, options);
-    const cutoff = now.getTime() - retentionDays * DAY_MS;
+    const globalOptions = options;
+    const repositoryModes = [];
+    const quotaLimits = new Map();
     const candidates = [];
     const deleted = [];
     const skipped = [...listed.skipped];
+    const quotas = [];
     for (const repository of listed.repositories) {
+        let local;
+        try {
+            local = globalOptions.repositoryPolicy?.(repository) ?? null;
+        }
+        catch (error) {
+            skipped.push({ repository, reason: `local-storage-policy-invalid: ${message(error)}` });
+            repositoryModes.push({ repository, mode: "invalid" });
+            continue;
+        }
+        if (local && !local.enabled) {
+            skipped.push({ repository, reason: "local-storage-policy-disabled" });
+            repositoryModes.push({ repository, mode: "disabled" });
+            continue;
+        }
+        const options = local
+            ? {
+                ...globalOptions,
+                retentionDays: local.retentionDays ?? globalOptions.retentionDays,
+                keepNewest: local.keepNewest ?? globalOptions.keepNewest,
+                maxCount: local.maxCount ?? globalOptions.maxCount,
+                maxAllocatedBytes: local.maxAllocatedBytes ?? globalOptions.maxAllocatedBytes,
+                apply: Boolean(globalOptions.apply && !local.dryRun),
+            }
+            : globalOptions;
+        quotaLimits.set(repository, options);
+        repositoryModes.push({ repository, mode: options.apply ? "apply" : "preview" });
+        const keepNewest = options.keepNewest ?? 1;
+        const cutoff = now.getTime() - (options.retentionDays ?? 3) * DAY_MS;
         const repositoryBackups = listed.backups.filter((entry) => entry.repository === repository);
-        const planned = repositoryBackups.slice(keepNewest).filter((entry) => entry.timestamp < cutoff);
+        const budgeted = options.maxCount !== undefined || options.maxAllocatedBytes !== undefined;
+        const protectedPaths = new Set(repositoryBackups
+            .slice(0, budgeted ? Math.max(1, keepNewest) : keepNewest)
+            .map((entry) => entry.path));
+        if ((options.protectRecoverable || budgeted) && repositoryBackups.length > 0) {
+            // Bounded integrity probes. If no rollback is proved, fail closed instead
+            // of deleting older backups that might be the only recoverable copy.
+            const rollback = repositoryBackups.slice(0, 32).find(recoverableBackup);
+            if (!rollback) {
+                skipped.push({ repository, reason: "no-proven-recoverable-backup" });
+                const allocated = repositoryBackups.every((entry) => entry.allocatedBytes !== null)
+                    ? repositoryBackups.reduce((sum, entry) => sum + (entry.allocatedBytes ?? 0), 0)
+                    : null;
+                quotas.push({
+                    repository,
+                    retainedCount: repositoryBackups.length,
+                    retainedAllocatedBytes: allocated,
+                    overQuota: (options.maxCount !== undefined && repositoryBackups.length > options.maxCount) ||
+                        (options.maxAllocatedBytes !== undefined &&
+                            allocated !== null &&
+                            allocated > options.maxAllocatedBytes)
+                        ? true
+                        : options.maxAllocatedBytes !== undefined && allocated === null
+                            ? null
+                            : false,
+                });
+                continue;
+            }
+            protectedPaths.add(rollback.path);
+        }
+        let retainedCount = repositoryBackups.length;
+        let retainedAllocatedBytes = repositoryBackups.every((entry) => entry.allocatedBytes !== null)
+            ? repositoryBackups.reduce((sum, entry) => sum + (entry.allocatedBytes ?? 0), 0)
+            : null;
+        const planned = [];
+        for (const entry of [...repositoryBackups].reverse()) {
+            if (protectedPaths.has(entry.path))
+                continue;
+            const countExceeded = options.maxCount !== undefined && retainedCount > options.maxCount;
+            const bytesExceeded = options.maxAllocatedBytes !== undefined &&
+                retainedAllocatedBytes !== null &&
+                retainedAllocatedBytes > options.maxAllocatedBytes;
+            if (entry.timestamp >= cutoff && !countExceeded && !bytesExceeded)
+                continue;
+            planned.push(entry);
+            retainedCount--;
+            if (retainedAllocatedBytes !== null)
+                retainedAllocatedBytes -= entry.allocatedBytes ?? 0;
+        }
+        // Preserve the established deterministic newest-first preview ordering.
+        planned.sort((a, b) => b.timestamp - a.timestamp || a.path.localeCompare(b.path));
+        if (options.maxAllocatedBytes !== undefined && retainedAllocatedBytes === null)
+            skipped.push({ repository, reason: "allocated-byte-measurement-unavailable" });
+        quotas.push({
+            repository,
+            retainedCount,
+            retainedAllocatedBytes,
+            overQuota: (options.maxCount !== undefined && retainedCount > options.maxCount) ||
+                (options.maxAllocatedBytes !== undefined &&
+                    retainedAllocatedBytes !== null &&
+                    retainedAllocatedBytes > options.maxAllocatedBytes)
+                ? true
+                : options.maxAllocatedBytes !== undefined && retainedAllocatedBytes === null
+                    ? null
+                    : false,
+        });
         candidates.push(...planned);
         if (!options.apply || planned.length === 0)
             continue;
         let lease;
         try {
+            assertStoragePolicyWritable(repository);
             lease = acquireRepairLease(repository, "backups prune");
+            assertStoragePolicyWritable(repository);
+            if (globalOptions.repositoryPolicy &&
+                JSON.stringify(globalOptions.repositoryPolicy(repository)) !== JSON.stringify(local))
+                throw new Error("local-storage-policy-changed-after-plan");
             const marker = path.join(repository, ".knodin", "promotion.json");
             if (markerExists(marker))
                 throw new Error("promotion-in-progress-or-malformed-marker");
             if (!safeLiveDatabase(repository))
                 throw new Error("missing-or-unsafe-live-database");
             const stateRoot = fs.realpathSync(path.join(repository, ".knodin"));
+            const protectedEntries = repositoryBackups.filter((entry) => protectedPaths.has(entry.path));
+            for (const entry of protectedEntries) {
+                const stat = fs.lstatSync(entry.path);
+                if (!stat.isFile() ||
+                    stat.isSymbolicLink() ||
+                    stat.dev !== entry.device ||
+                    stat.ino !== entry.inode ||
+                    stat.size !== entry.bytes ||
+                    stat.mtimeMs !== entry.modifiedAtMs)
+                    throw new Error("protected-backup-changed-after-plan");
+            }
+            if ((options.protectRecoverable || budgeted) && !protectedEntries.some(recoverableBackup))
+                throw new Error("protected-backup-no-longer-recoverable");
             for (const candidate of planned) {
                 try {
                     const name = path.basename(candidate.path);
@@ -238,8 +420,10 @@ export function pruneBackups(roots, options = {}) {
                         stat.size !== candidate.bytes ||
                         stat.dev !== candidate.device ||
                         stat.ino !== candidate.inode ||
-                        stat.mtimeMs !== candidate.modifiedAtMs)
+                        stat.mtimeMs !== candidate.modifiedAtMs ||
+                        (candidate.allocatedBytes !== null && stat.blocks * 512 !== candidate.allocatedBytes))
                         throw new Error("candidate-changed-after-plan");
+                    assertStoragePolicyWritable(repository);
                     fs.unlinkSync(candidate.path);
                     deleted.push(candidate);
                 }
@@ -255,6 +439,31 @@ export function pruneBackups(roots, options = {}) {
             lease?.release();
         }
     }
+    const observed = options.apply ? listBackups(roots, options) : null;
+    if (observed)
+        skipped.push(...observed.skipped);
+    const actualQuotas = observed?.repositories.map((repository) => {
+        const options = quotaLimits.get(repository) ?? globalOptions;
+        const entries = observed.backups.filter((entry) => entry.repository === repository);
+        const unknown = observed.skipped.some((entry) => entry.repository === repository) ||
+            entries.some((entry) => entry.allocatedBytes === null);
+        const retainedAllocatedBytes = unknown
+            ? null
+            : entries.reduce((sum, entry) => sum + (entry.allocatedBytes ?? 0), 0);
+        return {
+            repository,
+            retainedCount: entries.length,
+            retainedAllocatedBytes,
+            overQuota: (options.maxCount !== undefined && entries.length > options.maxCount) ||
+                (options.maxAllocatedBytes !== undefined &&
+                    retainedAllocatedBytes !== null &&
+                    retainedAllocatedBytes > options.maxAllocatedBytes)
+                ? true
+                : unknown && options.maxAllocatedBytes !== undefined
+                    ? null
+                    : false,
+        };
+    });
     return {
         schemaVersion: 1,
         mode: options.apply ? "apply" : "preview",
@@ -265,9 +474,60 @@ export function pruneBackups(roots, options = {}) {
         reclaimableBytes: candidates.reduce((sum, entry) => sum + entry.bytes, 0),
         deleted,
         deletedBytes: deleted.reduce((sum, entry) => sum + entry.bytes, 0),
+        deletedAllocatedBytes: deleted.every((entry) => entry.allocatedBytes !== null)
+            ? deleted.reduce((sum, entry) => sum + (entry.allocatedBytes ?? 0), 0)
+            : null,
+        quotas: actualQuotas ?? quotas,
+        quotaBasis: options.apply ? "observed-after-cleanup" : "planned-after-cleanup",
+        repositoryModes,
         skipped,
     };
 }
+/**
+ * Post-promotion maintenance for explicitly managed stores only. Call AFTER
+ * releasing the lifecycle lease; this takes the normal lease and never bypasses
+ * another holder. Legacy stores must obtain preview consent before supplying
+ * an enabled policy. This function never installs or overwrites any policy.
+ */
+export function maintainPromotionBackups(repository, policy, resolvePolicy) {
+    if (!policy?.enabled)
+        return { status: "disabled" };
+    try {
+        const state = path.join(path.resolve(repository), ".knodin");
+        const stateStat = fs.lstatSync(state);
+        if (!stateStat.isDirectory() || stateStat.isSymbolicLink())
+            return { status: "skipped", reason: "unsafe-state-directory" };
+        const result = pruneBackups([repository], {
+            repositoryPolicy: resolvePolicy
+                ? (repo) => {
+                    const current = resolvePolicy(repo);
+                    if (JSON.stringify(current) !== JSON.stringify(policy))
+                        throw new Error("local-storage-policy-changed-after-plan");
+                    return current;
+                }
+                : undefined,
+            depth: 0,
+            includeRegistry: false,
+            retentionDays: policy.retentionDays ?? MANAGED_BACKUP_DEFAULTS.retentionDays,
+            keepNewest: Math.max(1, policy.keepNewest ?? MANAGED_BACKUP_DEFAULTS.keepNewest),
+            maxCount: policy.maxCount ?? MANAGED_BACKUP_DEFAULTS.maxCount,
+            maxAllocatedBytes: policy.maxAllocatedBytes ?? MANAGED_BACKUP_DEFAULTS.maxAllocatedBytes,
+            protectRecoverable: true,
+            apply: !policy.dryRun,
+        });
+        return {
+            status: policy.dryRun
+                ? "preview"
+                : result.skipped.length
+                    ? "skipped"
+                    : "applied",
+            result,
+        };
+    }
+    catch (error) {
+        return { status: "failed", reason: message(error) };
+    }
+}
 function digest(content) {
     return crypto.createHash("sha256").update(content).digest("hex");
 }
@@ -293,7 +553,7 @@ function parseRetentionPolicy(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return null;
     const record = value;
-    if (!exactKeys(record, [
+    if (!exactKeys(Object.fromEntries(Object.entries(record).filter(([key]) => !["maxCount", "maxAllocatedBytes"].includes(key))), [
         "schemaVersion",
         "installedAt",
         "roots",
@@ -325,7 +585,8 @@ function parseRetentionPolicy(value) {
         record.launcher.length === 0 ||
         !record.launcher.every((part) => typeof part === "string") ||
         !path.isAbsolute(record.launcher[0]) ||
-        typeof record.dryRun !== "boolean")
+        typeof record.dryRun !== "boolean" ||
+        [record.maxCount, record.maxAllocatedBytes].some((value) => value !== undefined && (!Number.isSafeInteger(value) || value < 0)))
         return null;
     return record;
 }
@@ -468,6 +729,13 @@ function schedulerRun(platform, action, run, artifacts) {
     }
 }
 export function installBackupRetention(roots, options = {}) {
+    for (const [name, value] of Object.entries({
+        maxCount: options.maxCount,
+        maxAllocatedBytes: options.maxAllocatedBytes,
+    })) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+            throw new Error(`knodin backups retention: ${name} must be a non-negative safe integer`);
+    }
     const discovered = discoverBackupRepositories(roots, { ...options, includeRegistry: true });
     if (discovered.repositories.length === 0)
         throw new Error("knodin backups retention install: no repositories found in roots or registry");
@@ -480,6 +748,7 @@ export function installBackupRetention(roots, options = {}) {
         (!Number.isInteger(options.keepNewest) || options.keepNewest < 0 || options.keepNewest > 1000))
         throw new Error("knodin backups retention: --keep-newest must be an integer from 0 to 1000");
     const { policy: policyPath, stateRoot } = homes(options);
+    const previousInstalled = readInstalledRetention(options);
     const now = new Date();
     const launcher = (options.launcher ?? [process.execPath]).map((entry, index) => index === 0 ? path.resolve(entry) : entry);
     const policy = {
@@ -496,15 +765,18 @@ export function installBackupRetention(roots, options = {}) {
         ].sort((a, b) => a.localeCompare(b)),
         retentionDays: options.retentionDays ?? 3,
         keepNewest: options.keepNewest ?? 1,
+        maxCount: options.maxCount ?? previousInstalled.policy?.maxCount ?? MANAGED_BACKUP_DEFAULTS.maxCount,
+        maxAllocatedBytes: options.maxAllocatedBytes ??
+            previousInstalled.policy?.maxAllocatedBytes ??
+            MANAGED_BACKUP_DEFAULTS.maxAllocatedBytes,
         depth: options.depth ?? 5,
         schedule: validateSchedule(options.schedule ?? "04:17"),
         launcher,
-        dryRun: options.dryRun ?? false,
+        dryRun: options.dryRun ?? previousInstalled.policy?.dryRun ?? false,
     };
     const platform = options.platform ?? process.platform;
     if (!["darwin", "linux", "win32"].includes(platform))
         throw new Error(`knodin backups retention: scheduler unsupported on ${platform}`);
-    const previousInstalled = readInstalledRetention(options);
     const previous = previousInstalled.issues.length === 0 ? previousInstalled.receipt : null;
     const artifacts = schedulerArtifacts(policy, options);
     const run = options.run ?? commandRunner;
@@ -746,6 +1018,18 @@ export function removeBackupRetention(options = {}) {
     }
     return { schemaVersion: 1, removed: skipped.length === 0, skipped };
 }
+function installedConsentReader(options, installed) {
+    const snapshot = JSON.stringify({ policy: installed.policy, receipt: installed.receipt });
+    return (repository) => {
+        const current = readInstalledRetention(options);
+        if (!current.policy ||
+            !current.receipt ||
+            current.issues.length > 0 ||
+            JSON.stringify({ policy: current.policy, receipt: current.receipt }) !== snapshot)
+            throw new Error("installed retention consent changed; backups preserved");
+        return readLocalStoragePolicy(repository);
+    };
+}
 export function runInstalledRetention(options = {}) {
     const locations = homes(options);
     const installed = readInstalledRetention(options);
@@ -760,9 +1044,22 @@ export function runInstalledRetention(options = {}) {
         includeRegistry: true,
         retentionDays: policy.retentionDays,
         keepNewest: policy.keepNewest,
+        maxCount: policy.maxCount,
+        maxAllocatedBytes: policy.maxAllocatedBytes,
         apply: !policy.dryRun,
+        repositoryPolicy: installedConsentReader(options, installed),
     });
-    const record = { ...result, ranAt: (options.now ?? new Date()).toISOString() };
+    const record = {
+        ...result,
+        status: result.skipped.length
+            ? result.deleted.length
+                ? "partial"
+                : "skipped"
+            : result.repositoryModes.every((entry) => entry.mode === "preview")
+                ? "preview"
+                : "completed",
+        ranAt: (options.now ?? new Date()).toISOString(),
+    };
     atomicWrite(path.join(locations.stateRoot, "last-run.json"), `${JSON.stringify(record, null, 2)}\n`);
     appendRunLog(locations.stateRoot, record);
     return record;
@@ -803,7 +1100,32 @@ export function maybeRunOpportunisticRetention(repository, options = {}) {
         return { status: "disabled" };
     if (installed.issues.length > 0)
         return { status: "attention-required", issues: installed.issues };
+    try {
+        assertStoragePolicyWritable(repository);
+    }
+    catch (error) {
+        return { status: "skipped", reason: message(error) };
+    }
     const policy = installed.policy;
+    const currentRepository = canonicalDirectory(repository);
+    const isApplicable = (candidatePolicy) => currentRepository &&
+        canonicalDirectory(repository) === currentRepository &&
+        retentionAppliesToRepository(repository, candidatePolicy);
+    if (!isApplicable(policy))
+        return { status: "skipped", reason: "outside-retention-roots" };
+    const consentReader = installedConsentReader(options, installed);
+    let local;
+    try {
+        local = readLocalStoragePolicy(repository);
+    }
+    catch (error) {
+        return {
+            status: "attention-required",
+            issues: [`local-storage-policy-invalid: ${message(error)}`],
+        };
+    }
+    if (local && !local.enabled)
+        return { status: "disabled", reason: "local-storage-policy-disabled" };
     const duePath = path.join(locations.stateRoot, "due", `${digest(path.resolve(repository))}.json`);
     const due = readJson(duePath);
     const now = options.now ?? new Date();
@@ -815,8 +1137,19 @@ export function maybeRunOpportunisticRetention(repository, options = {}) {
         includeRegistry: false,
         retentionDays: policy.retentionDays,
         keepNewest: policy.keepNewest,
+        maxCount: policy.maxCount,
+        maxAllocatedBytes: policy.maxAllocatedBytes,
         apply: !policy.dryRun,
+        repositoryPolicy: (target) => {
+            if (!isApplicable(policy))
+                throw new Error("installed retention consent changed; backups preserved");
+            return consentReader(target);
+        },
     });
+    if (result.skipped.length > 0)
+        return { status: "skipped", result };
+    if (policy.dryRun || local?.dryRun)
+        return { status: "preview", result };
     atomicWrite(duePath, `${JSON.stringify({ schemaVersion: 1, ranAt: now.toISOString() })}\n`);
     return { status: "ran", result };
 }

package/dist/src/cli-model.js

@@ -188,12 +188,24 @@ function addBackupCommands(program, capture) {
         .option("--apply", "delete exact preview candidates after revalidation")
         .addOption(option("--retention-days <count>", "retention window in days", "integer"))
         .addOption(option("--keep-newest <count>", "newest backups retained per repository", "integer"))
+        .addOption(option("--max-count <count>", "hard backup count budget", "integer"))
+        .addOption(option("--max-bytes <count>", "allocated backup byte budget", "integer"))
         .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
         .option("--jsonl", "stream one record per line");
+    const policy = backups.command("policy").description("manage repository storage budgets");
+    for (const action of ["preview", "apply"])
+        leaf(policy, `${action} [roots...]`, `${action} repository storage policy`, capture)
+            .addOption(option("--max-count <count>", "hard backup count budget", "integer"))
+            .addOption(option("--max-bytes <count>", "allocated backup byte budget", "integer"))
+            .addOption(option("--reserve-bytes <count>", "minimum free-space reserve", "integer"))
+            .addOption(new Option("--mode <mode>", "maintenance mode").choices(["enabled", "disabled", "preview"]));
+    leaf(policy, "status [roots...]", "inspect repository storage policy", capture);
     const retention = backups.command("retention").description("manage opt-in ongoing retention");
     leaf(retention, "install [roots...]", "install daily and opportunistic retention", capture)
         .addOption(option("--retention-days <count>", "retention window in days", "integer"))
         .addOption(option("--keep-newest <count>", "newest backups retained per repository", "integer"))
+        .addOption(option("--max-count <count>", "hard backup count budget", "integer"))
+        .addOption(option("--max-bytes <count>", "allocated backup byte budget", "integer"))
         .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
         .option("--schedule <time>", "daily local HH:MM schedule")
         .option("--dry-run", "install a policy that logs without deleting")