harnery 0.36.0 → 0.38.0

package/dist/core/artifacts/index.js

@@ -8,13 +8,22 @@
  * expired, inactive, untracked managed unit is deletable.
  */
 import { spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
-import { artifactAutoCleanEnabled, artifactAutoCleanIntervalHours, artifactDefaultRetentionDays, } from "../config.js";
+import { artifactAutoCleanEnabled, artifactAutoCleanIntervalHours, artifactDefaultRetentionDays, artifactMaxBytes, artifactMaxUnitBytes, } from "../config.js";
 import { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.js";
 export { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.js";
+export function artifactCapabilities() {
+    return {
+        schema_version: ARTIFACT_SCHEMA_VERSION,
+        holds: true,
+        atomic_create_holds: true,
+        owner_scoped_unhold: true,
+        explicit_v1_migration: true,
+    };
+}
 export function artifactsRoot(repoRoot) {
     return join(resolve(repoRoot), ARTIFACTS_DIR);
 }
@@ -23,6 +32,9 @@ export function configuredArtifactRetentionDays(repoRoot) {
     return artifactDefaultRetentionDays(repoRoot);
 }
 export function createArtifact(repoRoot, input) {
+    return withArtifactLock(repoRoot, () => createArtifactUnlocked(repoRoot, input));
+}
+function createArtifactUnlocked(repoRoot, input) {
     const now = input.now ?? new Date();
     assertValidDate(now, "now");
     const slug = normalizeSlug(input.slug);
@@ -31,11 +43,17 @@ export function createArtifact(repoRoot, input) {
     const purpose = input.purpose.trim();
     if (!purpose)
         throw new Error("purpose must not be empty");
-    const retentionDays = positiveDays(input.retentionDays);
+    const expiresAt = input.retentionMinutes !== undefined
+        ? addMinutes(now, positiveMinutes(input.retentionMinutes))
+        : addDays(now, positiveDays(input.retentionDays));
     const artifactId = input.id ?? randomUUID();
     if (!isSafeId(artifactId)) {
         throw new Error("artifact id must use ASCII letters, digits, hyphens, or underscores");
     }
+    const holds = (input.holds ?? []).map((hold) => makeHold(hold, input.actor, now));
+    if (new Set(holds.map((hold) => hold.id)).size !== holds.length) {
+        throw new Error("duplicate hold id");
+    }
     const root = artifactsRoot(repoRoot);
     mkdirSync(root, { recursive: true });
     const date = now.toISOString().slice(0, 10);
@@ -43,14 +61,16 @@ export function createArtifact(repoRoot, input) {
     mkdirSync(path);
     const manifest = {
         schema_version: ARTIFACT_SCHEMA_VERSION,
+        holds,
         artifact_id: artifactId,
         slug,
         purpose,
         created_at: now.toISOString(),
         created_by: input.actor,
         retention: {
-            expires_at: addDays(now, retentionDays).toISOString(),
+            expires_at: expiresAt.toISOString(),
         },
+        ...(input.big ? { oversize_acknowledged: true } : {}),
     };
     atomicWriteManifest(path, manifest);
     return { path, manifest };
@@ -75,17 +95,22 @@ export function inventoryArtifacts(repoRoot, opts = {}) {
     for (const name of names) {
         rows.push(classifyArtifactPath(repoRoot, join(root, name), now, freshnessSeconds));
     }
-    return rows;
+    return applyArtifactBudgets(repoRoot, rows);
 }
 export function showArtifact(repoRoot, ref, opts = {}) {
     const path = resolveArtifactRef(repoRoot, ref);
-    const entry = classifyArtifactPath(repoRoot, path, opts.now ?? new Date(), opts.freshnessSeconds ?? 600);
+    const entry = inventoryArtifacts(repoRoot, opts).find((row) => row.path === path);
+    if (!entry)
+        throw new Error(`artifact "${ref}" was not found`);
     const parsed = readManifest(path);
     if (!parsed.ok)
         throw new Error(parsed.reason);
     return { entry, manifest: parsed.manifest };
 }
 export function renewArtifact(repoRoot, ref, days, reason, input = {}) {
+    return withArtifactLock(repoRoot, () => renewArtifactUnlocked(repoRoot, ref, days, reason, input));
+}
+function renewArtifactUnlocked(repoRoot, ref, days, reason, input) {
     const now = input.now ?? new Date();
     assertValidDate(now, "now");
     const retentionDays = positiveDays(days);
@@ -108,6 +133,9 @@ export function renewArtifact(repoRoot, ref, days, reason, input = {}) {
     return manifest;
 }
 export function releaseArtifact(repoRoot, ref, input = {}) {
+    return withArtifactLock(repoRoot, () => releaseArtifactUnlocked(repoRoot, ref, input));
+}
+function releaseArtifactUnlocked(repoRoot, ref, input) {
     const now = input.now ?? new Date();
     assertValidDate(now, "now");
     const path = resolveArtifactRef(repoRoot, ref);
@@ -122,20 +150,187 @@ export function releaseArtifact(repoRoot, ref, input = {}) {
     atomicWriteManifest(path, manifest);
     return manifest;
 }
+export function holdArtifact(repoRoot, ref, input) {
+    const hold = makeHold(input, input.actor, input.now ?? new Date());
+    return withArtifactLock(repoRoot, () => {
+        const path = resolveArtifactRef(repoRoot, ref);
+        const parsed = readManifest(path);
+        if (!parsed.ok)
+            throw new Error(parsed.reason);
+        const previous = parsed.manifest.holds.find((item) => item.id === hold.id);
+        if (previous) {
+            if (previous.set_by.instance_id !== input.actor.instance_id ||
+                previous.reason !== hold.reason) {
+                throw new Error("hold id already exists with a different owner or reason");
+            }
+            return parsed.manifest;
+        }
+        const manifest = { ...parsed.manifest, holds: [...parsed.manifest.holds, hold] };
+        atomicWriteManifest(path, manifest);
+        return manifest;
+    });
+}
+export function unholdArtifact(repoRoot, ref, id, input) {
+    if (!validHoldId(id))
+        throw new Error("invalid hold id");
+    if (!validActor(input.actor))
+        throw new Error("a valid hold actor is required");
+    return withArtifactLock(repoRoot, () => {
+        const path = resolveArtifactRef(repoRoot, ref);
+        const parsed = readManifest(path);
+        if (!parsed.ok)
+            throw new Error(parsed.reason);
+        const hold = parsed.manifest.holds.find((item) => item.id === id);
+        if (!hold)
+            return parsed.manifest;
+        if (hold.set_by.instance_id !== input.actor.instance_id) {
+            throw new Error("only the hold owner may remove this hold");
+        }
+        const manifest = {
+            ...parsed.manifest,
+            holds: parsed.manifest.holds.filter((item) => item.id !== id),
+        };
+        atomicWriteManifest(path, manifest);
+        return manifest;
+    });
+}
+/** Adopt untracked loose files and legacy directories without changing directory paths. */
+export function adoptUnmanagedArtifactFiles(repoRoot, input) {
+    if (input.yes)
+        return withArtifactLock(repoRoot, () => adoptUnmanagedArtifactFilesUnlocked(repoRoot, input));
+    return adoptUnmanagedArtifactFilesUnlocked(repoRoot, input);
+}
+function adoptUnmanagedArtifactFilesUnlocked(repoRoot, input) {
+    const now = input.now ?? new Date();
+    const candidates = [];
+    for (const row of inventoryArtifacts(repoRoot, { now })) {
+        if (row.classification !== "unmanaged")
+            continue;
+        try {
+            const stat = lstatSync(row.path);
+            if (stat.isSymbolicLink() || containsTrackedPath(repoRoot, row.path))
+                continue;
+            if (stat.isFile()) {
+                candidates.push({ path: row.path, name: row.name, bytes: stat.size, kind: "file" });
+                continue;
+            }
+            if (stat.isDirectory() && !existsSync(join(row.path, ARTIFACT_MANIFEST))) {
+                const bytes = safeTreeSize(row.path);
+                if (bytes !== null && normalizeSlug(row.name)) {
+                    candidates.push({ path: row.path, name: row.name, bytes, kind: "directory" });
+                }
+            }
+        }
+        catch {
+            // A racing or unreadable entry stays unmanaged.
+        }
+    }
+    const candidateBytes = candidates.reduce((sum, row) => sum + row.bytes, 0);
+    const fileBytes = candidates.reduce((sum, row) => sum + (row.kind === "file" ? row.bytes : 0), 0);
+    const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
+    const requiresBig = fileBytes > maxUnitBytes ||
+        candidates.some((row) => row.kind === "directory" && row.bytes > maxUnitBytes);
+    const preview = {
+        candidates,
+        candidate_bytes: candidateBytes,
+        requires_big: requiresBig,
+        adopted_artifact_id: null,
+        adopted_path: null,
+        adopted_directories: 0,
+    };
+    if (!input.yes || candidates.length === 0)
+        return preview;
+    if (requiresBig && !input.big) {
+        throw new Error("unmanaged adoption exceeds the per-bundle ceiling; repeat with --big");
+    }
+    // Revalidate every exact source before creating a destination. A changed,
+    // tracked, linked, or non-regular entry aborts the whole adoption.
+    for (const candidate of candidates) {
+        const stat = lstatSync(candidate.path);
+        const bytes = stat.isDirectory() ? safeTreeSize(candidate.path) : stat.size;
+        if (stat.isSymbolicLink() ||
+            bytes !== candidate.bytes ||
+            containsTrackedPath(repoRoot, candidate.path)) {
+            throw new Error(`unmanaged entry changed before adoption: ${candidate.name}`);
+        }
+        if (candidate.kind === "file" ? !stat.isFile() : !stat.isDirectory()) {
+            throw new Error(`unmanaged entry changed before adoption: ${candidate.name}`);
+        }
+    }
+    const files = candidates.filter((candidate) => candidate.kind === "file");
+    const created = files.length
+        ? createArtifactUnlocked(repoRoot, {
+            slug: "adopted-unmanaged",
+            purpose: input.purpose,
+            retentionDays: input.retentionDays,
+            actor: input.actor,
+            now,
+            big: input.big,
+        })
+        : null;
+    for (const candidate of files)
+        renameSync(candidate.path, join(created.path, candidate.name));
+    const retentionDays = positiveDays(input.retentionDays);
+    const directories = candidates.filter((candidate) => candidate.kind === "directory");
+    for (const candidate of directories) {
+        atomicWriteManifest(candidate.path, {
+            schema_version: ARTIFACT_SCHEMA_VERSION,
+            holds: [],
+            artifact_id: randomUUID(),
+            slug: normalizeSlug(candidate.name),
+            purpose: `${input.purpose}: ${candidate.name}`,
+            created_at: now.toISOString(),
+            created_by: input.actor,
+            retention: { expires_at: addDays(now, retentionDays).toISOString() },
+            ...(input.big ? { oversize_acknowledged: true } : {}),
+        });
+    }
+    return {
+        ...preview,
+        adopted_artifact_id: created?.manifest.artifact_id ?? null,
+        adopted_path: created?.path ?? null,
+        adopted_directories: directories.length,
+    };
+}
 export function cleanArtifacts(repoRoot, opts = {}) {
+    if (!opts.yes)
+        return inventoryArtifacts(repoRoot, opts);
+    try {
+        return withArtifactLock(repoRoot, () => cleanArtifactsUnlocked(repoRoot, opts));
+    }
+    catch (error) {
+        return inventoryArtifacts(repoRoot, opts).map((row) => row.action === "would-delete"
+            ? {
+                ...row,
+                classification: "unknown",
+                action: "keep",
+                reason: errorMessage("cleanup refused", error),
+            }
+            : row);
+    }
+}
+function cleanArtifactsUnlocked(repoRoot, opts) {
     const now = opts.now ?? new Date();
     const freshnessSeconds = opts.freshnessSeconds ?? 600;
     const rows = inventoryArtifacts(repoRoot, { now, freshnessSeconds });
     if (!opts.yes)
         return rows;
     return rows.map((entry) => {
-        if (entry.classification !== "managed-expired")
+        if (entry.action !== "would-delete")
             return entry;
         // Reclassify immediately before removal. A renewal, release-state change,
         // heartbeat, symlink swap, or tracked file added since inventory must win.
-        const current = classifyArtifactPath(repoRoot, entry.path, now, freshnessSeconds);
-        if (current.classification !== "managed-expired")
+        const current = inventoryArtifacts(repoRoot, { now, freshnessSeconds }).find((row) => row.path === entry.path);
+        if (!current) {
+            return { ...entry, classification: "unknown", reason: "entry disappeared", action: "keep" };
+        }
+        if (current.action !== "would-delete" ||
+            current.artifact_id !== entry.artifact_id ||
+            current.bytes !== entry.bytes ||
+            current.last_modified_at !== entry.last_modified_at ||
+            current.expires_at !== entry.expires_at) {
             return current;
+        }
         try {
             const top = lstatSync(current.path);
             if (!top.isDirectory() || top.isSymbolicLink()) {
@@ -264,7 +459,16 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
         last_modified_at: new Date(effectiveLastModifiedMs).toISOString(),
         expires_at: effectiveExpiresAt,
         owner_instance_id: manifest.created_by?.instance_id ?? null,
+        oversize_acknowledged: manifest.oversize_acknowledged === true,
     });
+    if (manifest.holds.length > 0) {
+        return {
+            ...base,
+            classification: "managed-held",
+            reason: `held: ${manifest.holds.map((hold) => hold.id).join(", ")}`,
+            action: "keep",
+        };
+    }
     if (base.bytes === null || lastModifiedMs === null) {
         return {
             ...base,
@@ -309,6 +513,38 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
         action: "would-delete",
     };
 }
+function applyArtifactBudgets(repoRoot, inputRows) {
+    const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
+    const maxBytes = artifactMaxBytes(repoRoot);
+    const rows = inputRows.map((row) => ({ ...row }));
+    for (const row of rows) {
+        if (row.classification === "managed-current" &&
+            row.bytes !== null &&
+            row.bytes > maxUnitBytes &&
+            !row.oversize_acknowledged) {
+            row.classification = "managed-oversize";
+            row.reason = `bundle uses ${row.bytes} bytes, above the ${maxUnitBytes}-byte ceiling without --big`;
+            row.action = "would-delete";
+        }
+    }
+    const managedBytes = rows.reduce((sum, row) => sum + (row.artifact_id && row.bytes !== null ? row.bytes : 0), 0);
+    let retainedBytes = managedBytes -
+        rows.reduce((sum, row) => sum + (row.action === "would-delete" && row.bytes !== null ? row.bytes : 0), 0);
+    if (retainedBytes <= maxBytes)
+        return rows;
+    const candidates = rows
+        .filter((row) => row.classification === "managed-current" && row.action === "keep" && row.bytes !== null)
+        .sort((left, right) => `${left.expires_at ?? ""}\0${left.created_at ?? ""}\0${left.name}`.localeCompare(`${right.expires_at ?? ""}\0${right.created_at ?? ""}\0${right.name}`));
+    for (const row of candidates) {
+        if (retainedBytes <= maxBytes)
+            break;
+        row.classification = "managed-over-budget";
+        row.reason = `repository artifact budget is ${maxBytes} bytes; earliest-expiring inactive bundles are removed first`;
+        row.action = "would-delete";
+        retainedBytes -= row.bytes ?? 0;
+    }
+    return rows;
+}
 function readManifest(path) {
     const manifestPath = join(path, ARTIFACT_MANIFEST);
     if (!existsSync(manifestPath)) {
@@ -316,11 +552,24 @@ function readManifest(path) {
     }
     let value;
     try {
+        const unit = lstatSync(path);
+        const stat = lstatSync(manifestPath);
+        if (!unit.isDirectory() ||
+            unit.isSymbolicLink() ||
+            !stat.isFile() ||
+            stat.isSymbolicLink() ||
+            stat.size > 1024 * 1024) {
+            return { ok: false, reason: "manifest must be a bounded regular file in a direct directory" };
+        }
         value = JSON.parse(readFileSync(manifestPath, "utf8"));
     }
     catch (error) {
         return { ok: false, reason: errorMessage("manifest is unreadable", error) };
     }
+    return parseArtifactManifest(value);
+}
+/** Validate only the current schema. Legacy conversion belongs to migrateArtifacts. */
+export function parseArtifactManifest(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return { ok: false, reason: "manifest must be a JSON object" };
     }
@@ -328,6 +577,11 @@ function readManifest(path) {
     if (m.schema_version !== ARTIFACT_SCHEMA_VERSION) {
         return { ok: false, reason: `unsupported schema_version ${String(m.schema_version)}` };
     }
+    if (!Array.isArray(m.holds) ||
+        m.holds.some((hold) => !validHold(hold)) ||
+        new Set(m.holds.map((hold) => hold.id)).size !== m.holds.length) {
+        return { ok: false, reason: "invalid holds" };
+    }
     if (!isSafeId(m.artifact_id))
         return { ok: false, reason: "invalid artifact_id" };
     if (typeof m.slug !== "string" || !m.slug || normalizeSlug(m.slug) !== m.slug) {
@@ -357,16 +611,147 @@ function readManifest(path) {
     if (m.released_by !== undefined && !validActor(m.released_by)) {
         return { ok: false, reason: "invalid released_by" };
     }
+    if (m.oversize_acknowledged !== undefined && typeof m.oversize_acknowledged !== "boolean") {
+        return { ok: false, reason: "invalid oversize_acknowledged" };
+    }
     return { ok: true, manifest: m };
 }
 function atomicWriteManifest(path, manifest) {
     const target = join(path, ARTIFACT_MANIFEST);
     const tmp = `${target}.tmp.${process.pid}.${randomUUID().slice(0, 8)}`;
-    writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
-        encoding: "utf8",
-        mode: 0o600,
-    });
-    renameSync(tmp, target);
+    try {
+        writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        renameSync(tmp, target);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+/** Explicit, bounded v1 cutover. Preview never writes; every applied unit keeps its exact preimage. */
+export function migrateArtifacts(repoRoot, opts = {}) {
+    const migrate = () => {
+        const root = artifactsRoot(repoRoot);
+        if (!existsSync(root))
+            return [];
+        return readdirSync(root)
+            .sort()
+            .map((name) => {
+            const path = join(root, name);
+            try {
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink() || !stat.isDirectory())
+                    throw new Error("not a direct directory");
+                if (containsTrackedPath(repoRoot, path))
+                    throw new Error("artifact contains tracked files");
+                const target = join(path, ARTIFACT_MANIFEST);
+                const manifestStat = lstatSync(target);
+                if (!manifestStat.isFile() ||
+                    manifestStat.isSymbolicLink() ||
+                    manifestStat.size > 1024 * 1024) {
+                    throw new Error("manifest is not a bounded regular file");
+                }
+                const preimage = readFileSync(target, "utf8");
+                const legacy = JSON.parse(preimage);
+                if (legacy?.schema_version !== 1) {
+                    return {
+                        path,
+                        action: "keep",
+                        reason: `schema_version ${String(legacy?.schema_version)} is not a migration source`,
+                    };
+                }
+                if (Object.hasOwn(legacy, "holds"))
+                    throw new Error("v1 manifest unexpectedly contains holds");
+                const parsed = parseArtifactManifest({
+                    ...legacy,
+                    schema_version: ARTIFACT_SCHEMA_VERSION,
+                    holds: [],
+                });
+                if (!parsed.ok)
+                    throw new Error(parsed.reason);
+                const digest = createHash("sha256").update(preimage).digest("hex");
+                const preimagePath = join(resolve(repoRoot), ".harnery/artifact-migrations", `${digest}.v1.json`);
+                if (!opts.yes)
+                    return {
+                        path,
+                        action: "would-migrate",
+                        reason: "valid v1 manifest",
+                        preimage_path: preimagePath,
+                    };
+                mkdirSync(dirname(preimagePath), { recursive: true });
+                try {
+                    writeFileSync(preimagePath, preimage, { flag: "wx", mode: 0o600 });
+                }
+                catch (error) {
+                    if (error.code !== "EEXIST" ||
+                        lstatSync(preimagePath).isSymbolicLink() ||
+                        readFileSync(preimagePath, "utf8") !== preimage)
+                        throw error;
+                }
+                if (readFileSync(target, "utf8") !== preimage)
+                    throw new Error("manifest changed before migration");
+                atomicWriteManifest(path, parsed.manifest);
+                return {
+                    path,
+                    action: "migrated",
+                    reason: "v1 preimage preserved; identity and retention unchanged",
+                    preimage_path: preimagePath,
+                };
+            }
+            catch (error) {
+                return { path, action: "keep", reason: errorMessage("migration refused", error) };
+            }
+        });
+    };
+    return opts.yes ? withArtifactLock(repoRoot, migrate) : migrate();
+}
+/** A persistent directory lock fails closed on contention or a crashed owner. */
+function withArtifactLock(repoRoot, action) {
+    const lock = join(resolve(repoRoot), ".harnery/artifacts-mutation.lock");
+    mkdirSync(dirname(lock), { recursive: true });
+    try {
+        mkdirSync(lock);
+    }
+    catch (error) {
+        throw new Error(errorMessage("artifact store mutation lock unavailable; retry after its owner finishes", error));
+    }
+    try {
+        return action();
+    }
+    finally {
+        rmdirSync(lock);
+    }
+}
+function validHoldId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value);
+}
+function validHold(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const hold = value;
+    return (validHoldId(hold.id) &&
+        typeof hold.reason === "string" &&
+        !!hold.reason.trim() &&
+        validActor(hold.set_by) &&
+        validIso(hold.set_at));
+}
+function makeHold(input, actor, now) {
+    assertValidDate(now, "now");
+    if (!validActor(actor))
+        throw new Error("a valid hold actor is required");
+    if (!validHoldId(input.id))
+        throw new Error("invalid hold id");
+    if (typeof input.reason !== "string" || !input.reason.trim())
+        throw new Error("hold reason must not be empty");
+    return {
+        id: input.id,
+        reason: input.reason.trim(),
+        set_by: { ...actor },
+        set_at: now.toISOString(),
+    };
 }
 function ownerLiveness(repoRoot, instanceId, now, freshnessSeconds) {
     try {
@@ -460,6 +845,7 @@ function rowFor(path, name, repoRoot, classification, reason, bytes = safeTreeSi
         last_modified_at: null,
         expires_at: null,
         owner_instance_id: null,
+        oversize_acknowledged: false,
     };
 }
 function normalizeSlug(value) {
@@ -481,6 +867,15 @@ function positiveDays(value) {
 function addDays(date, days) {
     return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
 }
+function positiveMinutes(value) {
+    if (!Number.isInteger(value) || value <= 0 || value > 3650 * 24 * 60) {
+        throw new Error("retention minutes must be between 1 and 5256000");
+    }
+    return value;
+}
+function addMinutes(date, minutes) {
+    return new Date(date.getTime() + minutes * 60 * 1000);
+}
 function isSafeId(value) {
     return (typeof value === "string" &&
         value.length >= 8 &&

package/dist/core/config.d.ts

@@ -185,6 +185,14 @@ export declare function coordFreshnessSeconds(coordRoot?: string | null): number
  * `0` (or a negative value) disables automatic rotation.
  */
 export declare function eventLedgerRotateActiveBytes(coordRoot?: string | null): number;
+export interface EventLedgerArchivePolicy {
+    maxBytes: number;
+    maxAgeDays: number;
+    keepMin: number;
+    autoClean: boolean;
+}
+/** Bounded retention for closed V3 epochs under `ledgers/v3-archives`. */
+export declare function eventLedgerArchivePolicy(coordRoot?: string | null): EventLedgerArchivePolicy;
 /**
  * Resolve the standalone dashboard port.
  *
@@ -200,6 +208,10 @@ export declare function sessionFinalizationConfig(coordRoot?: string | null): Se
  * `artifacts.default_retention_days` -> 3 days.
  */
 export declare function artifactDefaultRetentionDays(coordRoot?: string | null): number;
+/** Soft repository budget for managed working artifacts. */
+export declare function artifactMaxBytes(coordRoot?: string | null): number;
+/** Size at which one bundle requires an explicit `artifacts create --big` acknowledgement. */
+export declare function artifactMaxUnitBytes(coordRoot?: string | null): number;
 /**
  * Whether the daily SessionStart sweep of expired artifact workspaces runs.
  * Precedence: `HARNERY_ARTIFACT_AUTO_CLEAN` (0/false disables) ->
@@ -208,6 +220,14 @@ export declare function artifactDefaultRetentionDays(coordRoot?: string | null):
  * `artifacts clean --yes`.
  */
 export declare function artifactAutoCleanEnabled(coordRoot?: string | null): boolean;
+/**
+ * Whether `qa-run` and `review-pack create` sweep expired page review packs
+ * out of the artifact store before starting. Precedence:
+ * `HARNERY_REVIEW_PACK_AUTO_CLEAN` (1/true enables, 0/false disables) ->
+ * `review_pack.auto_clean` -> disabled. The sweep deletes only packs whose
+ * manifest says `managed: true` with `retention.expires_at` in the past.
+ */
+export declare function reviewPackAutoCleanEnabled(coordRoot?: string | null): boolean;
 /**
  * Sweep cadence in hours. Env-only (`HARNERY_ARTIFACT_AUTO_CLEAN_INTERVAL_HOURS`,
  * mainly for tests): the cadence is an implementation detail, not policy, and

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}