@celilo/cli 1.1.0 → 1.2.0

package/CELILO_SUBSYSTEMS.md

@@ -200,6 +200,18 @@ warning naming every paused module and its age onto EVERY management-API result
 That last one is the important half: it does not depend on the operator choosing
 to look, which is how a forgotten pause actually gets found.
 
+## Management-host browser runtime
+
+- **The browser celilo provisions** — installed by `modules/celilo-mgmt/ansible/roles/celilo-mgmt/tasks/debian.yml` into `/var/lib/celilo/browsers`, behind `install_browser` (a manifest boolean **defaulting to false**, exactly how `install_docker` / `install_terraform` gate third-party-repo tooling: ~170 MB from an external CDN). The pin is `playwright_version` in `modules/celilo-mgmt/manifest.yml` — the fleet's single browser-version declaration. What is UNCONDITIONAL is the *declaration*, so a host that needs a browser and lacks one says so. It provisions `chromium-headless-shell`, **not** full Chromium: both builds on celilo-mgr are headless shells and `chromium.launch()` has been driving one in production the whole time, so the full browser would change what works rather than preserve it. Accepted ceiling: no headed browsing. macOS is an explicit `fail`, not a silent skip.
+- **The seam** — `packages/capabilities/src/browser.ts` — `resolveBrowser()` returns `{ browser, flavor, executablePath, browserVersion, playwrightVersion, revision }` read from the stable symlink `/var/lib/celilo/browsers/current/chrome` plus the descriptor `current/celilo-browser.json` the install writes. Consumers pass `executablePath` to their launcher, which bypasses Playwright's revision-keyed cache resolution — the revision is a property of the CLIENT version (1.55.1 → 1193, 1.60.0 → 1223), so without it a consumer's client bump silently moves the browser out from under it. **A plain exported function, deliberately NOT a capability and NOT a `HookContext` field**: an event-bus subscriber runs as its own subprocess with no hook context at all, and `lunacycle` — the one consumer — launches from both a hook and a subscriber. There is no `CapabilityRegistry` / `KNOWN_CAPABILITY_NAMES` entry and there should not be one.
+- **Two failures, two severities** — `BrowserUnavailableError.reason` is `'not_provisioned' | 'unusable'`, and the discriminant is load-bearing. Installation is opt-in, so *absent* is the NORMAL state of a host; a consumer reports it non-fatally. A module throws on any failing check item and celilo maps any fail → unhealthy → the module stays INSTALLED, so a single severity would take every browser-using module permanently unverified on any host that had not flipped a flag it never knew about. *Unusable* — dangling symlink, not executable, unreadable descriptor — is a regression and fails. **Provisioning status is decided from the BINARY, never from a directory existing**: a build directory present with no executable inside it satisfies every path check and then fails at launch.
+- **`system doctor` rows** — `apps/celilo/src/system/prereqs.ts` — `browser` and `fonts` joined `PREREQUISITES`. `PrerequisiteSpec.command` is the second check kind: an ABSOLUTE path switches presence from `command -v` to exists + executable + reports-a-version. ⚠️ **Never ask Playwright which executable it would use.** `chromium.executablePath()` reports the FULL browser while a headless launch opens the SHELL — measured disagreeing on one machine in one run — so on a shell-only host it validates a path that is not there while the binary that actually runs is fine. Because a not-provisioned browser is deliberately not a check failure, this row is the ONLY place an operator learns the host has none. `fonts` runs `fc-match sans-serif`, which resolves an actual face rather than merely proving fontconfig is installed, and displays the family — that is what decides whether a retained screenshot has legible glyphs.
+- **Per-run artifact directory** — `moduleArtifactDir(modulePath, runKey)` in the same file is the one definition of the module store's artifact layout, consumed by `apps/celilo/src/hooks/executor.ts` when it creates `HookContext.screenshotDir` and reachable from a bus subscriber that has no context. Per-run because a consumer writing fixed filenames — a reasonable thing to do — would otherwise overwrite itself every run and leave retention nothing to retain. The executor discards the directory when the hook wrote nothing, so an idle module accrues none; note it is created only AFTER every early return, because the capability pre-flight returns outside the `try/finally` that reclaims it and an earlier `mkdir` leaked one empty directory per affected run, forever.
+- **Artifacts reach the operator** — the executor collects EVERY file written to the run directory (`collectArtifacts`), carried as `HookResult.artifactPaths` (there is no `screenshotPath`; it was deleted, not deprecated). `apps/celilo/src/services/health-runner.ts` carries them onto `HealthCheckResult` — including the hook-FAILED branch, where they matter most because there are no named checks to explain anything — and `failingKeysFromHealthItems` (`services/alerting/keys.ts`) appends them to each failing item's `details`, which is the field that actually reaches an alert. Collecting them and stopping short of `details` would accomplish nothing. `apps/celilo/src/hooks/types.ts` exports `describeArtifacts`, the one renderer the three error-message sites share.
+- **Retention is by AGE, never by run count** — `apps/celilo/src/hooks/artifact-retention.ts` — 24 h plus a per-module byte ceiling, pruned on write so it needs no scheduler. Count-based pruning is the trap: for a persistent failure the FIRST artifact set carries the original cause and later ones repeat it, so "keep the last 5" discards the useful one within about an hour at a 15-minute cadence. A run is aged by its NEWEST file, not the directory's mtime, so an in-flight run cannot be evicted underneath itself. Artifacts are excluded from module backups (`modules/celilo-mgmt/scripts/on_backup.ts` `EXCLUDE_DIRS`) and preserved across `module update`.
+- **Pin-drift guardrail** — `apps/celilo/src/services/audit/browser-pin.ts` — the `browser_pin` drift category compares each module's BUNDLED `playwright-core` against the provisioned browser, and it compares **revisions, not version strings**: the revision is what has to match a build, and each client states its own in the `browsers.json` inside the package, so nobody maintains a version→revision table that would rot. It WARNS (`drift`) and never blocks — under D2 the consumer passes an explicit `executablePath`, so a mismatch is protocol skew rather than a failure. Silent when no browser is provisioned (the opt-in default) and when no module bundles a client (almost all of them); a check that fired in either case would put a permanent finding on every host in the fleet. Adding a `DriftCategory` does NOT create a monitor — only 3 of the 21 categories have one — so this is a `system audit` finding, not a page (D4).
+- Design and the declined alternatives (no probe capability, no fourth `builtin_check`, no concurrency semaphore, no off-box prober — each with its trigger): `openspec/changes/managed-browser-runtime/`.
+
 ## Generation & templating
 
 - **Generator** — `apps/celilo/src/templates/generator.ts` — `generateTemplates` (orchestration), plus Terraform/Ansible file handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^2.0.0",
+    "@celilo/capabilities": "^2.1.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.8.1",
     "@celilo/event-bus": "^0.6.0",

package/src/cli/commands/hook-run.ts

@@ -13,6 +13,7 @@ import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import { createConsoleLogger, createGaugeLogger } from '../../hooks/logger';
 import { runNamedHook } from '../../hooks/run-named-hook';
+import { describeArtifacts } from '../../hooks/types';
 import type { HookName } from '../../hooks/types';
 import type { ModuleManifest } from '../../manifest/schema';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
@@ -83,10 +84,8 @@ export async function handleHookRun(
     });
 
     if (!result.success) {
-      let errorMsg = result.error || 'Hook execution failed';
-      if (result.screenshotPath) {
-        errorMsg += `\n\nScreenshot saved: ${result.screenshotPath}`;
-      }
+      const errorMsg =
+        (result.error || 'Hook execution failed') + describeArtifacts(result.artifactPaths);
       return { success: false, error: errorMsg };
     }
 
@@ -109,10 +108,8 @@ export async function handleHookRun(
 
   if (!result.success) {
     gauge.stop(false);
-    let errorMsg = result.error || 'Hook execution failed';
-    if (result.screenshotPath) {
-      errorMsg += `\n\nScreenshot saved: ${result.screenshotPath}`;
-    }
+    const errorMsg =
+      (result.error || 'Hook execution failed') + describeArtifacts(result.artifactPaths);
     return { success: false, error: errorMsg };
   }
 

package/src/cli/commands/system-audit.ts

@@ -40,6 +40,7 @@ import { runAudit } from '../../services/audit';
 import type { DriftFinding, SystemAuditReport } from '../../services/audit';
 import { loadAbandonedOperations } from '../../services/audit/abandoned-operations';
 import { loadBackupAuditInfo } from '../../services/audit/backup-source';
+import { collectBrowserPinDeps } from '../../services/audit/browser-pin';
 import {
   type LatestCliVersionFetcher,
   fetchLatestCliVersion,
@@ -358,6 +359,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    browserPin: collectBrowserPinDeps(deployedModules),
     terraformPlan: {
       modules: terraformModules,
       run: realTerraformPlan,

package/src/cli/commands/system-doctor.ts

@@ -33,6 +33,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
+import { resolveBrowser } from '@celilo/capabilities';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import cliPkg from '../../../package.json' with { type: 'json' };
 import { getDbPath, getEventBusPath } from '../../config/paths';
@@ -279,6 +280,7 @@ function applyFix(drifted: DriftedDep[], cliRoot: string): string[] {
 function renderPrereqSection(): { lines: string[]; failingCount: number } {
   const checks = checkAllPrerequisites();
   const lines: string[] = [];
+  const browserFlavor = provisionedBrowserFlavor();
 
   lines.push('System prerequisites');
   // Right-pad column for alignment. Take the longest tool name +1
@@ -288,7 +290,16 @@ function renderPrereqSection(): { lines: string[]; failingCount: number } {
   for (const c of checks) {
     if (c.present && c.meetsMinimum) {
       const version = c.version ? c.version : `${ANSI.dim}(version unknown)${ANSI.reset}`;
-      lines.push(`  ${ANSI.green}✔${ANSI.reset} ${c.name.padEnd(nameCol)}  ${version}`);
+      // Flavour rides on the browser row because the ceiling it names is
+      // real — a headless-only build cannot run headed — and an operator
+      // reading doctor is the other party who benefits from that being
+      // legible rather than discovered by a launch failure. It cannot come
+      // from the check itself: a headless shell reports
+      // "Google Chrome for Testing <v>", the same string a full build
+      // prints, so only the descriptor knows which one is installed.
+      const flavor =
+        c.name === 'browser' && browserFlavor ? ` ${ANSI.dim}(${browserFlavor})${ANSI.reset}` : '';
+      lines.push(`  ${ANSI.green}✔${ANSI.reset} ${c.name.padEnd(nameCol)}  ${version}${flavor}`);
     } else if (c.present && !c.meetsMinimum) {
       // Present but below minimum (or version-parse failed with a minimum).
       const detail = c.version ? `${c.version} — below minimum required` : 'version unreadable';
@@ -306,6 +317,24 @@ function renderPrereqSection(): { lines: string[]; failingCount: number } {
   return { lines, failingCount: failingPrerequisites(checks).length };
 }
 
+/**
+ * Which flavour of browser is provisioned, or null when none is (or the
+ * descriptor cannot be read). Never throws — a doctor row is not worth
+ * failing the whole report over.
+ *
+ * This reads the DESCRIPTOR while the prerequisite check RUNS the binary.
+ * Those answer different questions and both are wanted: executing it is
+ * what distinguishes a real install from a build directory with no binary
+ * in it, and only the descriptor records what was installed.
+ */
+function provisionedBrowserFlavor(): string | null {
+  try {
+    return resolveBrowser().flavor;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * mtime (ms) of the installed dispatcher code (`@celilo/event-bus`
  * package.json). The fleet dispatcher check compares this against the

package/src/cli/commands/system-update.ts

@@ -27,6 +27,7 @@ import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { runAudit } from '../../services/audit';
 import { loadAbandonedOperations } from '../../services/audit/abandoned-operations';
+import { collectBrowserPinDeps } from '../../services/audit/browser-pin';
 import { fetchLatestCliVersion } from '../../services/audit/cli-version';
 import { unusedPublicDnsProbe } from '../../services/audit/public-dns';
 import { makeJournalReader, readAppliedMigrations } from '../../services/audit/schema';
@@ -536,6 +537,7 @@ export async function handleSystemUpdate(
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    browserPin: collectBrowserPinDeps(upgradableModules),
     terraformPlan: {
       modules: upgradableModules.map((m) => ({
         id: m.id,

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']);
+  });
+});