@celilo/cli 1.1.0 → 1.3.0

package/src/cli/index.ts

@@ -51,6 +51,7 @@ import {
 import { handleFirewallInterfaceList } from './commands/firewall-interface-list';
 import { handleHookRun } from './commands/hook-run';
 import {
+  handleIpamIpEdit,
   handleIpamIpListReservations,
   handleIpamIpReserve,
   handleIpamIpUnreserve,
@@ -608,6 +609,7 @@ Subcommands:
   config unset <id> <key>              Remove an override; follow the manifest again
 
   secret set <id> <key> <value>        Set encrypted module secret
+  secret get <id> <key>                Get a decrypted module secret value
   secret list <id>                     List module secrets
 
   show-config <id>                     Show all config including auto-derived values
@@ -1050,6 +1052,7 @@ VMID Commands:
 IP Commands:
   celilo ipam ip exclude <ip-range> --reason <reason> [--zone <zone>]
   celilo ipam ip include <ip-or-range> [--zone <zone>]
+  celilo ipam ip edit <ip> --reason <reason> [--zone <zone>]
   celilo ipam ip list-exclusions
 
 Description:
@@ -1069,6 +1072,9 @@ Examples:
   celilo ipam ip exclude 10.0.10.1-10.0.10.9 --reason "Infrastructure"
   celilo ipam ip exclude 192.168.0.1-192.168.0.150 --reason "DHCP managed range"
 
+  # Re-label an exclusion in place (no include/exclude dance, no allocation race)
+  celilo ipam ip edit 192.168.0.153 --reason "orphaned — safe to include"
+
   # List allocations and reservations
   celilo ipam list-allocations
   celilo ipam vmid list-reservations
@@ -2345,7 +2351,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return {
           success: false,
           error:
-            'IP action required (exclude, include, list-exclusions)\n\nRun "celilo ipam --help" for usage',
+            'IP action required (exclude, include, edit, list-exclusions)\n\nRun "celilo ipam --help" for usage',
         };
       }
       const ipArgs = parsed.args.slice(1);
@@ -2355,6 +2361,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       if (ipSubcommand === 'include') {
         return handleIpamIpUnreserve(ipArgs, parsed.flags);
       }
+      if (ipSubcommand === 'edit') {
+        return handleIpamIpEdit(ipArgs, parsed.flags);
+      }
       if (ipSubcommand === 'list-exclusions') {
         return handleIpamIpListReservations(ipArgs, parsed.flags);
       }

package/src/cli/tui/audit-state.ts

@@ -72,6 +72,7 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'cli_version',
   'schema',
   'capability_abi',
+  'browser_pin',
   'terraform_plan',
   'module_versions',
   'module_configs',
@@ -96,6 +97,7 @@ export const CATEGORY_LABELS: Record<DriftCategory, string> = {
   cli_version: 'CLI version',
   schema: 'Schema migrations',
   capability_abi: 'Capability ABI',
+  browser_pin: 'Browser pin',
   terraform_plan: 'Terraform plans',
   module_versions: 'Module versions',
   module_configs: 'Module configs',

package/src/db/schema.ts

@@ -60,6 +60,7 @@ export const IN_FLIGHT_STATES = [
 
 /**
  * Modules table - stores module metadata and manifest data
+ * @owner celilo — the module registry itself
  */
 export const modules = sqliteTable(
   'modules',
@@ -112,6 +113,7 @@ export const modules = sqliteTable(
  * `valueJson` only for arrays/objects. That was Defect 1 — TS types
  * generated from the manifest claimed `number` while the runtime
  * value was string. Now closed.
+ * @owner celilo — generic per-module KV; the migration destination (T9)
  */
 export const moduleConfigs = sqliteTable(
   'module_configs',
@@ -134,6 +136,7 @@ export const moduleConfigs = sqliteTable(
 /**
  * Capabilities table - stores registered capabilities provided by modules
  * Example: namecheap module provides dns_registrar capability
+ * @owner celilo — the brokering table, who provides what (T8)
  */
 export const capabilities = sqliteTable('capabilities', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -154,6 +157,7 @@ export const capabilities = sqliteTable('capabilities', {
  * Capability secrets table - stores encrypted secrets owned by capabilities
  * Values are encrypted with AES-256-GCM using master key
  * Example: dns-external capability owns TSIG secret
+ * @owner celilo — custody of ciphertext keyed by capability id; holds no format knowledge
  */
 export const capabilitySecrets = sqliteTable(
   'capability_secrets',
@@ -178,6 +182,7 @@ export const capabilitySecrets = sqliteTable(
 /**
  * Secrets table - stores encrypted secrets per module
  * Values are encrypted with AES-256-GCM using master key
+ * @owner celilo — custody of ciphertext keyed by module; holds no format knowledge
  */
 export const secrets = sqliteTable('secrets', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -196,6 +201,7 @@ export const secrets = sqliteTable('secrets', {
  * System configuration - system-wide settings
  * Used for $system: variables in templates
  * Examples: DNS servers, network settings, domain names
+ * @owner celilo — generic operator KV
  */
 export const systemConfig = sqliteTable('system_config', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -210,6 +216,7 @@ export const systemConfig = sqliteTable('system_config', {
  * System secrets table - stores encrypted system-level secrets
  * Values are encrypted with AES-256-GCM using master key
  * Examples: Proxmox root password, API tokens, SSH keys
+ * @owner celilo — generic operator KV, encrypted
  */
 export const systemSecrets = sqliteTable('system_secrets', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -225,6 +232,7 @@ export const systemSecrets = sqliteTable('system_secrets', {
 /**
  * Module integrity table - stores checksums and signature for package verification
  * Used for runtime auditing to detect tampering, missing files, or extra files
+ * @owner celilo — package checksums + signature, tamper detection
  */
 export const moduleIntegrity = sqliteTable('module_integrity', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -242,6 +250,7 @@ export const moduleIntegrity = sqliteTable('module_integrity', {
  * IPAM (IP Address Management) allocations table
  * Tracks VMID and IP address assignments per module
  * Prevents conflicts and enables automatic allocation from zone subnets
+ * @owner celilo — IPAM is a core primitive
  */
 export const ipAllocations = sqliteTable('ip_allocations', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -258,6 +267,7 @@ export const ipAllocations = sqliteTable('ip_allocations', {
  * IP reservations table
  * Allows users to reserve IPs for infrastructure or external services
  * IPAM allocator skips reserved IPs
+ * @owner celilo — IPAM is a core primitive
  */
 export const ipReservations = sqliteTable('ip_reservations', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -272,6 +282,7 @@ export const ipReservations = sqliteTable('ip_reservations', {
  * VMID reservations table
  * Allows users to reserve VMIDs for existing VMs or external systems
  * IPAM allocator skips reserved VMIDs
+ * @owner celilo — IPAM is a core primitive; infra-provider columns; out of scope per S17, not blessed
  */
 export const vmidReservations = sqliteTable('vmid_reservations', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -284,6 +295,7 @@ export const vmidReservations = sqliteTable('vmid_reservations', {
  * Module builds table
  * Tracks build metadata for modules with custom compilation requirements
  * Example: Caddy with RFC2136 DNS provider, custom Go binaries
+ * @owner celilo — build metadata per module version
  */
 export type BuildStatus = 'success' | 'failed' | 'in_progress';
 
@@ -381,6 +393,7 @@ export function isAllocatableZone(zone: NetworkZone): zone is AllocatableZone {
  * Container services table
  * Stores container service providers (Proxmox, Digital Ocean, etc.)
  * that can provision new containers/VMs on demand
+ * @owner celilo — infra-provider registry; infra-provider columns; out of scope per S17, not blessed
  */
 export const containerServices = sqliteTable('container_services', {
   id: text('id').primaryKey(), // UUID
@@ -405,6 +418,7 @@ export const containerServices = sqliteTable('container_services', {
  * Machines table
  * Stores pre-existing machines (Raspberry Pi, VPS, bare metal)
  * that users have added to the pool for hosting modules
+ * @owner celilo — the machine pool
  */
 export const machines = sqliteTable('machines', {
   id: text('id').primaryKey(), // UUID
@@ -450,6 +464,7 @@ export const machines = sqliteTable('machines', {
 /**
  * Module infrastructure table
  * Tracks which infrastructure (machine or container service) is used for each module
+ * @owner celilo — which infra hosts which module; infra-provider columns; out of scope per S17, not blessed
  */
 export const moduleInfrastructure = sqliteTable('module_infrastructure', {
   id: text('id').primaryKey(), // UUID
@@ -491,6 +506,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
  * `$infra:<name>.…`. `hostname` is the runtime DNS hostname (often == name, but
  * user/well-known-assignable), used by DNS and events. See
  * openspec/specs/module-systems-addressing/spec.md.
+ * @owner celilo — deployment state per addressed host; infra-provider columns; out of scope per S17, not blessed
  */
 export const moduleSystems = sqliteTable(
   'module_systems',
@@ -538,6 +554,7 @@ export const moduleSystems = sqliteTable(
  * Tracks routes registered by modules via public_web capability functions.
  * Routes are registered during on_install hooks and removed during on_uninstall.
  * The public_web provider (Caddy) uses these to generate its configuration.
+ * @owner capability:public_web — reverse-proxy configuration; migrates to the provider (T1)
  */
 export const webRoutes = sqliteTable(
   'web_routes',
@@ -576,6 +593,7 @@ export const webRoutes = sqliteTable(
  * Keyed by `firewall_ip` (the converge target) so multiple firewalls each render
  * their own set. Shared-core (not a per-module JSON file) so any firewall
  * provider reconciles against the one canonical store.
+ * @owner capability:firewall — one row is one DNAT rule; migrates to the provider (T2)
  */
 export const portForwards = sqliteTable(
   'port_forwards',
@@ -632,6 +650,7 @@ export const portForwards = sqliteTable(
  *
  * Distinct from a port forward: that publishes one backend on specific ports;
  * this is a whole origin subnet permitted to initiate into the segmented tiers.
+ * @owner capability:firewall — the firewall ruleset; migrates to the provider (T3)
  */
 export const trustedSources = sqliteTable(
   'trusted_sources',
@@ -678,6 +697,7 @@ export const trustedSources = sqliteTable(
  * until its LAST consumer is removed. The remote DNS record itself stays
  * (Namecheap DDNS has no delete API).
  * See designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B2).
+ * @owner celilo — claim ledger, deliberately stores no address (T4)
  */
 export const dnsRegistrations = sqliteTable(
   'dns_registrations',
@@ -721,6 +741,7 @@ export const dnsRegistrations = sqliteTable(
  * last module that wants the name goes away (design.md D5).
  *
  * The introducing module is the earliest row by `id`.
+ * @owner celilo — the consumer SET, dies with the last consumer (T5)
  */
 export const dnsRegistrationConsumers = sqliteTable(
   'dns_registration_consumers',
@@ -755,6 +776,7 @@ export const dnsRegistrationConsumers = sqliteTable(
  * modules at once — so absences are counted rather than reported, and become
  * their own finding only once they persist. A subject that answers has its row
  * dropped, which is what makes the count consecutive.
+ * @owner celilo — the audit subsystem's state about its own ability to observe (T7)
  */
 export const publicDnsEvidence = sqliteTable('public_dns_evidence', {
   subject: text('subject').primaryKey(),
@@ -775,6 +797,7 @@ export const publicDnsEvidence = sqliteTable('public_dns_evidence', {
  * `celilo system doctor` reads this to assert service hostnames resolve to
  * the firewall natIp (LAN-reachable) and not a zone-side container IP that
  * a LAN device can't route to. Rows die with either module via FK cascade.
+ * @owner capability:dns_internal — resolver configuration; migrates to the provider (T6)
  */
 export const dnsInternalRecords = sqliteTable(
   'dns_internal_records',
@@ -814,6 +837,7 @@ export const dnsInternalRecords = sqliteTable(
 /**
  * Backup storage providers - destinations for backup archives
  * Supports local filesystem and S3-compatible storage (AWS S3, MinIO, Backblaze B2, Wasabi)
+ * @owner celilo — backup destinations; infra-provider columns; out of scope per S17, not blessed
  */
 export type BackupStorageProvider = 'local' | 's3';
 
@@ -837,6 +861,7 @@ export const backupStorages = sqliteTable('backup_storages', {
 /**
  * Backup records - metadata for each backup taken
  * Tracks both system state backups and module data backups
+ * @owner celilo — backup metadata
  */
 export type BackupType = 'module_data' | 'system_state';
 export type BackupStatus = 'in_progress' | 'completed' | 'failed';
@@ -878,6 +903,7 @@ export const backups = sqliteTable('backups', {
  * The `pid` column carries the process that started the operation; a row whose
  * pid is no longer alive is treated as abandoned (the process crashed before
  * the completion update landed) and ignored by in-flight checks.
+ * @owner celilo — in-flight operation tracking
  */
 export type ModuleOperationKind =
   | 'deploy'
@@ -918,6 +944,7 @@ export const moduleOperations = sqliteTable('module_operations', {
  * approvals don't linger.
  *
  * See openspec/specs/base-module-aspects/spec.md D2 + D7.
+ * @owner celilo — operator consent, per module version + scope hash
  */
 export const aspectApprovals = sqliteTable(
   'aspect_approvals',
@@ -961,6 +988,7 @@ export const aspectApprovals = sqliteTable(
  * ponytail: one key per principal (a person wanting a second device makes a
  * second principal, e.g. `alice-laptop`). If multiple keys per identity is ever
  * needed, split into an `api_keys` child table — not worth it yet.
+ * @owner celilo — remote-API identity + grants
  */
 export const apiPrincipals = sqliteTable('api_principals', {
   id: text('id').primaryKey(), // UUID
@@ -1008,6 +1036,7 @@ export type AlertState = 'pending' | 'firing' | 'acked' | 'suppressed' | 'resolv
 /**
  * People celilo can reach. Deliberately independent of any transport or
  * module — a person exists before any notification module is deployed.
+ * @owner celilo — deliberately independent of any transport or module
  */
 export const people = sqliteTable('people', {
   id: text('id').primaryKey(), // UUID
@@ -1029,6 +1058,7 @@ export const people = sqliteTable('people', {
  * adding a recipient would require redeploying the module. signal-cli holds
  * one credential (its own registration); recipients are addresses, not
  * credentials. See design D8.
+ * @owner celilo — who celilo pages and how; the calibration example in section 5
  */
 export const routes = sqliteTable(
   'routes',
@@ -1064,6 +1094,7 @@ export const routes = sqliteTable(
 /**
  * Named, reusable escalation policy. Steps reference ROUTES rather than
  * people — "page Peter" is ambiguous about which transport to use.
+ * @owner celilo — named escalation policy
  */
 export const escalationPolicies = sqliteTable('escalation_policies', {
   id: text('id').primaryKey(), // UUID
@@ -1079,7 +1110,11 @@ export const escalationPolicies = sqliteTable('escalation_policies', {
   updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
 
-/** One ordered step of an escalation policy. Delay is from escalation start. */
+/**
+ * One ordered step of an escalation policy. Delay is from escalation start.
+ *
+ * @owner celilo — the ordered steps of one
+ */
 export const escalationSteps = sqliteTable(
   'escalation_steps',
   {
@@ -1105,6 +1140,7 @@ export const escalationSteps = sqliteTable(
  * The module manifest's `hooks.health_check.interval` is only a SUGGESTION;
  * this row is the effective schedule and an operator edit survives module
  * upgrades. See design D3.
+ * @owner celilo — what runs, how often, how failures route
  */
 export const monitors = sqliteTable(
   'monitors',
@@ -1139,6 +1175,7 @@ export const monitors = sqliteTable(
  * whether the last run actually ran (design D5) — without a persisted
  * outcome there is nothing to distinguish "found nothing wrong" from
  * "couldn't look".
+ * @owner celilo — did the run execute at all
  */
 export const monitorRuns = sqliteTable('monitor_runs', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -1155,6 +1192,7 @@ export const monitorRuns = sqliteTable('monitor_runs', {
  * A deliberate, time-boxed suppression source. Today only deploys create
  * these — a deploy is the same suppression mechanism as a machine-down alert,
  * with a window as the source instead of an ancestor alert (design D7).
+ * @owner celilo — time-boxed deliberate suppression
  */
 export const suppressionWindows = sqliteTable('suppression_windows', {
   id: text('id').primaryKey(), // UUID
@@ -1174,6 +1212,7 @@ export const suppressionWindows = sqliteTable('suppression_windows', {
  * `acked`, `suppressed`, and `silenced` are deliberately THREE separate
  * concerns (design S5) — collapsing any two is how alerting systems become
  * untrustworthy.
+ * @owner celilo — the alert lifecycle
  */
 export const alerts = sqliteTable(
   'alerts',
@@ -1265,6 +1304,7 @@ export const alerts = sqliteTable(
  * Per DELIVERY, not per alert: the token identifies WHO replied, which is
  * what "an ack from the secondary is broadcast to everyone paged" needs, and
  * doubles as the audit trail (design D10).
+ * @owner celilo — one outbound message + its reply token
  */
 export const notificationDeliveries = sqliteTable('notification_deliveries', {
   id: text('id').primaryKey(), // UUID

package/src/hooks/artifact-retention.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Retention is by AGE, and the test that matters is the one asserting the
+ * FIRST failing run survives a long streak. A count-based rule passes every
+ * other test here and fails that one — which is exactly the bug this
+ * policy exists to avoid, since the first artifact set carries the original
+ * cause and later ones repeat it.
+ *
+ * Uses a real temp directory rather than an injected filesystem: mtime
+ * ordering and directory sizing are the behaviour under test, and a fake
+ * would be asserting my own model of them.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ARTIFACT_RETENTION_MS, pruneModuleArtifacts } from './artifact-retention';
+
+const HOUR = 60 * 60 * 1000;
+const NOW = Date.UTC(2026, 7, 18, 12, 0, 0);
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'celilo-artifacts-'));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+/** Create a run directory whose files are `ageMs` old, with `bytes` of content. */
+function makeRun(name: string, ageMs: number, bytes = 16): string {
+  const dir = join(root, name);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, 'spa-failure.png');
+  writeFileSync(file, Buffer.alloc(bytes));
+  const when = new Date(NOW - ageMs);
+  utimesSync(file, when, when);
+  utimesSync(dir, when, when);
+  return dir;
+}
+
+function survivors(): string[] {
+  return readdirSync(root).sort();
+}
+
+describe('pruneModuleArtifacts', () => {
+  test('keeps everything inside the retention window', () => {
+    makeRun('run-a', 1 * HOUR);
+    makeRun('run-b', 23 * HOUR);
+
+    const outcome = pruneModuleArtifacts(root, { now: NOW });
+
+    expect(outcome.removed).toEqual([]);
+    expect(survivors()).toEqual(['run-a', 'run-b']);
+  });
+
+  test('prunes what is older than the retention window', () => {
+    makeRun('stale', 25 * HOUR);
+    makeRun('fresh', 1 * HOUR);
+
+    pruneModuleArtifacts(root, { now: NOW });
+
+    expect(survivors()).toEqual(['fresh']);
+  });
+
+  test('the boundary is exclusive: exactly at the window, it stays', () => {
+    // The off-by-one is the whole risk in a rule expressed as an inequality.
+    makeRun('exactly-24h', ARTIFACT_RETENTION_MS);
+    makeRun('a-ms-older', ARTIFACT_RETENTION_MS + 1);
+
+    pruneModuleArtifacts(root, { now: NOW });
+
+    expect(survivors()).toEqual(['exactly-24h']);
+  });
+
+  test('THE POINT: the first failure of a long streak survives', () => {
+    // A 12-hour streak at the 15-minute health cadence — every run failing,
+    // every one writing artifacts. The first set carries the original cause;
+    // "keep the last N" would have discarded it hours ago.
+    for (let quarterHour = 0; quarterHour <= 48; quarterHour++) {
+      makeRun(`run-${String(quarterHour).padStart(3, '0')}`, quarterHour * 15 * 60 * 1000);
+    }
+
+    pruneModuleArtifacts(root, { now: NOW });
+
+    const kept = survivors();
+    expect(kept).toContain('run-048'); // the oldest — the first failure
+    expect(kept).toContain('run-000'); // the most recent
+    expect(kept.length).toBe(49);
+  });
+
+  test('the size ceiling evicts oldest-first, and only down to the ceiling', () => {
+    makeRun('oldest', 3 * HOUR, 1000);
+    makeRun('middle', 2 * HOUR, 1000);
+    makeRun('newest', 1 * HOUR, 1000);
+
+    const outcome = pruneModuleArtifacts(root, { now: NOW, sizeCeilingBytes: 2500 });
+
+    // 3000 bytes exceeds 2500; dropping the oldest brings it to 2000.
+    expect(survivors()).toEqual(['middle', 'newest']);
+    expect(outcome.removed).toEqual([join(root, 'oldest')]);
+    expect(outcome.retainedBytes).toBe(2000);
+  });
+
+  test('a run still being written is aged by its newest file, not the directory', () => {
+    // The directory's own mtime can lag a file rewritten in place, which
+    // would let an in-flight run read as old enough to evict.
+    const dir = join(root, 'in-flight');
+    mkdirSync(dir, { recursive: true });
+    const old = new Date(NOW - 30 * HOUR);
+    utimesSync(dir, old, old);
+    const stale = join(dir, 'old.txt');
+    writeFileSync(stale, 'x');
+    utimesSync(stale, old, old);
+    writeFileSync(join(dir, 'just-written.png'), 'y'); // now
+
+    pruneModuleArtifacts(root, { now: NOW });
+
+    expect(survivors()).toEqual(['in-flight']);
+  });
+
+  test('a missing artifact root is not an error', () => {
+    expect(() => pruneModuleArtifacts(join(root, 'never-created'), { now: NOW })).not.toThrow();
+  });
+
+  test('loose files beside the run directories are left alone', () => {
+    writeFileSync(join(root, 'cookies.json'), '{}');
+    makeRun('stale', 30 * HOUR);
+
+    pruneModuleArtifacts(root, { now: NOW });
+
+    expect(survivors()).toEqual(['cookies.json']);
+  });
+});

package/src/hooks/artifact-retention.ts

@@ -0,0 +1,159 @@
+/**
+ * Retention for the per-run artifact directories hooks write into.
+ *
+ * **By AGE, not by run count**, and the difference is not cosmetic. For a
+ * persistent failure — the normal case, since a broken deploy stays broken
+ * — the FIRST artifact set carries the original cause and runs 2..N are the
+ * same wall re-hit. A count-based rule therefore keeps the least
+ * informative sets and discards the one worth having: at the 15-minute
+ * cadence a health monitor runs on, "keep the last 5" is seventy-five
+ * minutes, and the operator typically reads the alert hours later.
+ *
+ * The size ceiling is the backstop, not the policy. ~96 runs a day of
+ * full-page screenshots on a management host is a `disk_space` alert
+ * waiting to happen, and celilo has a builtin check that would fire on it.
+ *
+ * Pruning is a pure function of mtime, so it needs no streak-tracking
+ * state and cannot drift out of sync with what is on disk.
+ */
+
+import { readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** How long a run's artifacts are kept. Long enough to survive a night. */
+export const ARTIFACT_RETENTION_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Total bytes of retained artifacts per module. Generous — this is the
+ * backstop against an unforeseen writer, not the mechanism that normally
+ * reclaims space.
+ */
+export const ARTIFACT_SIZE_CEILING_BYTES = 64 * 1024 * 1024;
+
+export interface PruneOptions {
+  /** Defaults to `Date.now()`; injected so tests need no sleeping. */
+  now?: number;
+  retentionMs?: number;
+  sizeCeilingBytes?: number;
+}
+
+export interface PruneOutcome {
+  /** Directories removed, oldest first. */
+  removed: string[];
+  /** Bytes retained after pruning. */
+  retainedBytes: number;
+}
+
+interface RunDirectory {
+  path: string;
+  mtimeMs: number;
+  bytes: number;
+}
+
+/**
+ * Remove aged-out and over-ceiling run directories under a module's
+ * artifact root.
+ *
+ * Best effort by construction: a hook run must never fail because a stale
+ * directory could not be deleted, so every filesystem error is swallowed
+ * and the outcome reports only what actually happened.
+ */
+export function pruneModuleArtifacts(
+  artifactRoot: string,
+  options: PruneOptions = {},
+): PruneOutcome {
+  const now = options.now ?? Date.now();
+  const retentionMs = options.retentionMs ?? ARTIFACT_RETENTION_MS;
+  const ceiling = options.sizeCeilingBytes ?? ARTIFACT_SIZE_CEILING_BYTES;
+
+  const runs = readRunDirectories(artifactRoot);
+  // Oldest first, so both passes evict from the same end.
+  runs.sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+  const removed: string[] = [];
+  const surviving: RunDirectory[] = [];
+  for (const run of runs) {
+    if (now - run.mtimeMs > retentionMs) {
+      if (remove(run.path)) removed.push(run.path);
+      continue;
+    }
+    surviving.push(run);
+  }
+
+  let retainedBytes = surviving.reduce((sum, run) => sum + run.bytes, 0);
+  while (retainedBytes > ceiling && surviving.length > 0) {
+    // biome-ignore lint/style/noNonNullAssertion: length checked above
+    const oldest = surviving.shift()!;
+    if (remove(oldest.path)) {
+      removed.push(oldest.path);
+      retainedBytes -= oldest.bytes;
+    } else {
+      // Undeletable: stop rather than spin, and leave it counted.
+      break;
+    }
+  }
+
+  return { removed, retainedBytes };
+}
+
+function readRunDirectories(artifactRoot: string): RunDirectory[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(artifactRoot);
+  } catch {
+    return []; // No artifact root yet — nothing to prune.
+  }
+
+  const runs: RunDirectory[] = [];
+  for (const entry of entries) {
+    const path = join(artifactRoot, entry);
+    try {
+      if (!statSync(path).isDirectory()) continue;
+      runs.push({ path, mtimeMs: newestMtime(path), bytes: directoryBytes(path) });
+    } catch {
+      // Vanished mid-scan, or unreadable. Not ours to fix.
+    }
+  }
+  return runs;
+}
+
+/**
+ * Age a run by the NEWEST file in it, not by the directory's own mtime.
+ * A directory's mtime tracks its last entry change, which on some
+ * filesystems does not move when a file inside it is rewritten in place —
+ * so a run still being appended to could otherwise read as old enough to
+ * evict while the check that owns it is still running.
+ */
+function newestMtime(dir: string): number {
+  let newest = statSync(dir).mtimeMs;
+  for (const file of readdirSync(dir)) {
+    try {
+      newest = Math.max(newest, statSync(join(dir, file)).mtimeMs);
+    } catch {
+      // Skip what we cannot stat.
+    }
+  }
+  return newest;
+}
+
+function directoryBytes(dir: string): number {
+  let total = 0;
+  for (const file of readdirSync(dir)) {
+    try {
+      const stat = statSync(join(dir, file));
+      if (stat.isFile()) total += stat.size;
+    } catch {
+      // Skip what we cannot stat.
+    }
+  }
+  return total;
+}
+
+function remove(path: string): boolean {
+  try {
+    rmSync(path, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}