@celilo/cli 0.17.0 → 0.19.0

package/src/services/audit/disk-space.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  DISK_BLOCKED_PERCENT,
+  DISK_DRIFT_PERCENT,
+  type DiskUsageResult,
+  auditDiskSpace,
+} from './disk-space';
+
+function usage(over: Partial<DiskUsageResult> = {}): DiskUsageResult {
+  return {
+    hostname: 'celilo-mgr',
+    ipAddress: '10.0.120.10',
+    usedPercent: 10,
+    availableBytes: 102 * 1024 ** 3,
+    ...over,
+  };
+}
+
+describe('auditDiskSpace', () => {
+  test('a healthy filesystem produces no finding', () => {
+    expect(auditDiskSpace({ results: [usage({ usedPercent: 10 })] })).toEqual([]);
+  });
+
+  test('just below the threshold stays quiet', () => {
+    const findings = auditDiskSpace({ results: [usage({ usedPercent: DISK_DRIFT_PERCENT - 1 })] });
+    expect(findings).toEqual([]);
+  });
+
+  test('at the drift threshold reports drift, naming host and usage', () => {
+    const findings = auditDiskSpace({ results: [usage({ usedPercent: DISK_DRIFT_PERCENT })] });
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.severity).toBe('drift');
+    expect(findings[0]?.code).toBe('disk_low');
+    expect(findings[0]?.message).toContain('celilo-mgr');
+    expect(findings[0]?.message).toContain('85%');
+  });
+
+  test('at the blocked threshold escalates to blocked', () => {
+    const findings = auditDiskSpace({ results: [usage({ usedPercent: DISK_BLOCKED_PERCENT })] });
+
+    expect(findings[0]?.severity).toBe('blocked');
+    expect(findings[0]?.code).toBe('disk_critical');
+  });
+
+  // The alert has to name the host to act on, and suppression resolves a
+  // machine's ancestor key from its HOSTNAME (alerting/suppression.ts). A UUID
+  // subject produces a key suppression can never match — that is #596, filed
+  // against machines_reachable. This check must not repeat it.
+  test('subjects the finding on the hostname, never a UUID', () => {
+    const findings = auditDiskSpace({
+      results: [usage({ hostname: 'iot', usedPercent: 99 })],
+    });
+
+    expect(findings[0]?.subject).toBe('iot');
+  });
+
+  test('only the offending host is reported in a mixed fleet', () => {
+    const findings = auditDiskSpace({
+      results: [
+        usage({ hostname: 'celilo-mgr', usedPercent: 96 }),
+        usage({ hostname: 'iot', usedPercent: 12 }),
+        usage({ hostname: 'dns-ext', usedPercent: 40 }),
+      ],
+    });
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.subject).toBe('celilo-mgr');
+  });
+
+  test('reports free space alongside the percentage', () => {
+    const findings = auditDiskSpace({
+      results: [usage({ usedPercent: 96, availableBytes: 6 * 1024 ** 3 })],
+    });
+
+    expect(findings[0]?.message).toContain('6.0 GB free');
+  });
+
+  // Unmeasurable must not read as healthy — but it must not page either, since
+  // machines_reachable is already alerting for the same dead host.
+  test('an unmeasurable host is recorded as todo, not as healthy', () => {
+    const findings = auditDiskSpace({
+      results: [usage({ hostname: 'iot', usedPercent: null, message: 'ssh: connect timed out' })],
+    });
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.severity).toBe('todo');
+    expect(findings[0]?.code).toBe('disk_unmeasured');
+    expect(findings[0]?.details).toContain('timed out');
+  });
+
+  test('an unreachable host does not hide a filling one', () => {
+    const findings = auditDiskSpace({
+      results: [
+        usage({ hostname: 'iot', usedPercent: null, message: 'unreachable' }),
+        usage({ hostname: 'celilo-mgr', usedPercent: 97 }),
+      ],
+    });
+
+    expect(findings.map((f) => f.subject).sort()).toEqual(['celilo-mgr', 'iot']);
+    expect(findings.find((f) => f.subject === 'celilo-mgr')?.severity).toBe('blocked');
+  });
+
+  test('every finding carries the disk_space category', () => {
+    const findings = auditDiskSpace({
+      results: [usage({ usedPercent: 99 }), usage({ hostname: 'iot', usedPercent: null })],
+    });
+
+    expect(findings.every((f) => f.category === 'disk_space')).toBe(true);
+  });
+});

package/src/services/audit/disk-space.ts

@@ -0,0 +1,114 @@
+/**
+ * Disk-space check.
+ *
+ * Catches the failure that had no detector at all: a filesystem filling up.
+ * celilo-mgr reached 34% and climbing at ~4.8 GB/hour from leaked backup
+ * staging, and the only reason anyone noticed was an operator running `df` by
+ * eye. Every one of the eighteen configured monitors watched module health or
+ * machine reachability; not one looked at disk.
+ *
+ * Reports EARLY, not at exhaustion. A check that fires once a filesystem is
+ * full reports an outage instead of preventing one, so the thresholds leave
+ * room to act: `drift` at 85% is "you have time", `blocked` at 95% is "you do
+ * not". On a 117 GB root that is ~17 GB and ~6 GB of headroom respectively —
+ * hours at the leak rate that motivated this, days at any normal one.
+ *
+ * The audit consumes pre-computed measurements so it stays unit-testable
+ * without a live filesystem or SSH client, exactly like `machines-reachable`.
+ */
+
+import type { DriftFinding } from './types';
+
+/** Usage at or above this is divergence worth an operator's attention. */
+export const DISK_DRIFT_PERCENT = 85;
+
+/** Usage at or above this is close enough to exhaustion to gate on. */
+export const DISK_BLOCKED_PERCENT = 95;
+
+export interface DiskUsageResult {
+  /**
+   * User-facing hostname, and the identifier the finding is keyed by.
+   *
+   * NOT the machine's UUID. Suppression resolves a machine's ancestor key from
+   * its hostname (`machineAlertKey` in alerting/suppression.ts), so a finding
+   * subjected on the UUID produces an alert key suppression can never match —
+   * which is exactly the bug filed as #596 against `machines_reachable`. Using
+   * the hostname here also satisfies CLAUDE.md: users never see UUIDs.
+   */
+  hostname: string;
+  ipAddress: string;
+  /** Percent of the root filesystem in use, or null when it could not be measured. */
+  usedPercent: number | null;
+  /** Bytes still available. Omitted when unmeasured. */
+  availableBytes?: number;
+  /** Why the measurement failed, when `usedPercent` is null. */
+  message?: string;
+}
+
+export interface DiskSpaceAuditDeps {
+  results: DiskUsageResult[];
+}
+
+function humanBytes(bytes: number): string {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value.toFixed(value < 10 && unit > 0 ? 1 : 0)} ${units[unit]}`;
+}
+
+export function auditDiskSpace(deps: DiskSpaceAuditDeps): DriftFinding[] {
+  const findings: DriftFinding[] = [];
+
+  for (const result of deps.results) {
+    // Unmeasurable is NOT healthy — but it does not page either. The host is
+    // already unreachable, `machines_reachable` is already alerting on it, and
+    // a second page for one dead host is noise. `todo` records without
+    // notifying, which is the existing severity for exactly that.
+    if (result.usedPercent === null) {
+      findings.push({
+        category: 'disk_space',
+        severity: 'todo',
+        code: 'disk_unmeasured',
+        message: `${result.hostname}: disk usage could not be measured`,
+        details: result.message,
+        remediation:
+          'The host is unreachable or `df` failed on it. `machines_reachable` covers reachability; this finding only records that disk is currently unknown, not that it is healthy.',
+        actionable: false,
+        subject: result.hostname,
+      });
+      continue;
+    }
+
+    if (result.usedPercent < DISK_DRIFT_PERCENT) continue;
+
+    const critical = result.usedPercent >= DISK_BLOCKED_PERCENT;
+    const free =
+      result.availableBytes === undefined ? '' : `, ${humanBytes(result.availableBytes)} free`;
+
+    findings.push({
+      category: 'disk_space',
+      severity: critical ? 'blocked' : 'drift',
+      code: critical ? 'disk_critical' : 'disk_low',
+      message: `${result.hostname}: root filesystem ${result.usedPercent}% full${free}`,
+      details: critical
+        ? `At or above ${DISK_BLOCKED_PERCENT}% the host is close enough to exhaustion that writes can begin failing. On the management server a full root filesystem takes the event bus and dispatcher with it, including whatever scheduled work would otherwise clean up.`
+        : `At or above ${DISK_DRIFT_PERCENT}% there is still room to act. Find the growth before it becomes an outage rather than after.`,
+      remediation: [
+        `Find what is growing on ${result.hostname}:`,
+        '  df -h /',
+        '  sudo du -xh --max-depth=2 / | sort -h | tail -30',
+        'Then fix the source — a retention policy, a size cap, or a prune',
+        'schedule. A one-off delete leaves the same thing growing.',
+      ].join('\n'),
+      // Multi-step diagnosis, not a one-shot celilo command.
+      actionable: false,
+      subject: result.hostname,
+    });
+  }
+
+  return findings;
+}

package/src/services/audit/index.test.ts

@@ -26,6 +26,7 @@ const emptyDeps = {
   moduleConfigs: { modules: [] },
   health: { results: [] },
   backups: { modules: [] },
+  abandonedOperations: { records: [] },
   undeployedModules: { modules: [] },
   unconfiguredModules: { modules: [] },
   servicesCredentials: { results: [] },

package/src/services/audit/index.ts

@@ -10,6 +10,10 @@
  * truth for what audit can detect is this file's `AuditDeps` shape.
  */
 
+import {
+  type AbandonedOperationsAuditDeps,
+  auditAbandonedOperations,
+} from './abandoned-operations';
 import { type BackupsAuditDeps, auditBackups } from './backups';
 import { type CapabilityAbiAuditDeps, auditCapabilityAbi } from './capability-abi';
 import { type CliVersionAuditDeps, auditCliVersion } from './cli-version';
@@ -48,6 +52,7 @@ export interface AuditDeps {
   moduleConfigs: ModuleConfigsAuditDeps;
   health: HealthAuditDeps;
   backups: BackupsAuditDeps;
+  abandonedOperations: AbandonedOperationsAuditDeps;
   undeployedModules: UndeployedModulesAuditDeps;
   unconfiguredModules: UnconfiguredModulesAuditDeps;
   servicesCredentials: ServicesCredentialsAuditDeps;
@@ -99,6 +104,10 @@ export async function runAudit(
     wrap('module_configs', auditModuleConfigs(deps.moduleConfigs)),
     wrap('health', auditHealth(deps.health)),
     wrap('backups', auditBackups(deps.backups)),
+    wrap(
+      'abandoned_operations',
+      Promise.resolve(auditAbandonedOperations(deps.abandonedOperations)),
+    ),
     wrap('undeployed_modules', auditUndeployedModules(deps.undeployedModules)),
     wrap('unconfigured_modules', auditUnconfiguredModules(deps.unconfiguredModules)),
     wrap('services_credentials', auditServicesCredentials(deps.servicesCredentials)),

package/src/services/audit/types.ts

@@ -30,12 +30,14 @@ export type DriftCategory =
   | 'module_configs'
   | 'health'
   | 'backups'
+  | 'abandoned_operations'
   | 'undeployed_modules'
   | 'unconfigured_modules'
   | 'services_credentials'
   | 'secrets_decryptable'
   | 'services_reachable'
   | 'machines_reachable'
+  | 'disk_space'
   | 'transport_reads'
   | 'trusted_sources';
 

package/src/services/backup-create.ts

@@ -4,7 +4,6 @@
  */
 
 import { copyFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDbPath } from '../config/paths';
@@ -20,6 +19,7 @@ import { encryptFileToFile } from './backup-cipher';
 import { buildManifest } from './backup-manifest';
 import { completeBackup, createBackupRecord, failBackup, listBackups } from './backup-metadata';
 import type { BackupSchedule } from './backup-schedule';
+import { stagingDirFor } from './backup-staging';
 import {
   createStorageProvider,
   getBackupStorage,
@@ -113,7 +113,7 @@ export async function createSystemStateBackup(
   });
   const opId = startOperation('__system__', 'backup');
 
-  const tempDir = join(tmpdir(), `celilo-backup-${record.id}`);
+  const tempDir = stagingDirFor(record.id);
 
   try {
     mkdirSync(tempDir, { recursive: true });
@@ -328,7 +328,7 @@ export async function createModuleBackup(
   // Envelope layout (v1.0):
   //   manifest.json   - schema version, host, moduleId, dataSchemaVersion
   //   data/           - on_backup hook artifacts (the hook treats this as backup_dir)
-  const tempDir = join(tmpdir(), `celilo-backup-${record.id}`);
+  const tempDir = stagingDirFor(record.id);
   const envelopeDir = join(tempDir, 'envelope');
   const dataDir = join(envelopeDir, 'data');
 
@@ -496,7 +496,7 @@ export async function importModuleBackup(
     moduleVersion: manifest.version,
   });
 
-  const tempDir = join(tmpdir(), `celilo-backup-${record.id}`);
+  const tempDir = stagingDirFor(record.id);
   const artifactDir = join(tempDir, 'artifacts');
 
   try {

package/src/services/backup-in-flight-refusal.test.ts

@@ -129,6 +129,7 @@ describe('backup/restore in-flight refusal', () => {
         status: 'completed' as const,
         errorMessage: null,
         name: null,
+        pid: process.pid,
         startedAt: new Date(),
         completedAt: null,
       };
@@ -152,6 +153,7 @@ describe('backup/restore in-flight refusal', () => {
         status: 'completed' as const,
         errorMessage: null,
         name: null,
+        pid: process.pid,
         startedAt: new Date(),
         completedAt: null,
       };

package/src/services/backup-metadata.ts

@@ -43,6 +43,10 @@ export function createBackupRecord(params: CreateBackupParams): BackupRecord {
     metadata: {},
     status: 'in_progress' as BackupStatus,
     errorMessage: null,
+    // Recorded so the staging reaper can distinguish a live backup from one
+    // whose process was killed before its `finally` ran — see
+    // services/backup-staging.ts.
+    pid: process.pid,
     startedAt: now,
     completedAt: null,
   };

package/src/services/backup-staging.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type ReapStagingDeps,
+  STAGING_PREFIX,
+  STAGING_TTL_MS,
+  type StagingOwner,
+  reapOrphanedStaging,
+  stagingDirFor,
+} from './backup-staging';
+
+const NOW = new Date('2026-08-06T12:00:00Z').getTime();
+
+function deps(
+  owners: Record<string, StagingOwner | null>,
+  options: {
+    dirs?: string[];
+    runnablePids?: number[];
+    unremovable?: string[];
+  } = {},
+): ReapStagingDeps & { removed: string[] } {
+  const removed: string[] = [];
+  return {
+    removed,
+    listStagingDirs: () => options.dirs ?? Object.keys(owners).map((id) => stagingDirFor(id)),
+    lookupOwner: (id) => owners[id] ?? null,
+    isPidRunnable: (pid) => (options.runnablePids ?? []).includes(pid),
+    remove: (path) => {
+      if (options.unremovable?.includes(path)) throw new Error('EACCES');
+      removed.push(path);
+    },
+    now: () => NOW,
+  };
+}
+
+function owner(over: Partial<StagingOwner> = {}): StagingOwner {
+  return { status: 'in_progress', pid: 111, startedAt: new Date(NOW - 60_000), ...over };
+}
+
+describe('reapOrphanedStaging', () => {
+  test('reclaims staging whose backup record no longer exists', () => {
+    const d = deps({ 'gone-id': null });
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed).toHaveLength(1);
+    expect(report.reclaimed[0]?.reason).toBe('record-absent');
+    expect(d.removed).toEqual([stagingDirFor('gone-id')]);
+  });
+
+  test.each([['completed'], ['failed']])('reclaims staging for a %s record', (status) => {
+    const d = deps({ 'done-id': owner({ status }) });
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed[0]?.reason).toBe('record-terminal');
+    expect(d.removed).toEqual([stagingDirFor('done-id')]);
+  });
+
+  test('reclaims staging whose owning process is dead', () => {
+    // in_progress, inside the TTL — only the liveness probe can tell.
+    const d = deps({ 'dead-id': owner({ pid: 999 }) }, { runnablePids: [] });
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed[0]?.reason).toBe('process-dead');
+    expect(d.removed).toEqual([stagingDirFor('dead-id')]);
+  });
+
+  // The one that must never regress: a running backup writing gigabytes into
+  // its staging dir must survive a concurrent sweep.
+  test('KEEPS staging owned by a live backup', () => {
+    const d = deps({ 'live-id': owner({ pid: 111 }) }, { runnablePids: [111] });
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed).toHaveLength(0);
+    expect(report.kept).toEqual([stagingDirFor('live-id')]);
+    expect(d.removed).toEqual([]);
+  });
+
+  test('reclaims a record past the TTL even when its pid looks alive', () => {
+    // Guards pid reuse: after the pid space wraps, a stale record's pid names
+    // an unrelated live process and liveness alone would strand this forever.
+    const d = deps(
+      { 'stale-id': owner({ pid: 111, startedAt: new Date(NOW - STAGING_TTL_MS - 1) }) },
+      { runnablePids: [111] },
+    );
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed[0]?.reason).toBe('expired');
+  });
+
+  test('keeps a pid-less record until it expires, then reclaims it', () => {
+    const fresh = deps({ 'old-fmt': owner({ pid: null }) });
+    expect(reapOrphanedStaging(fresh).kept).toHaveLength(1);
+
+    const expired = deps({
+      'old-fmt': owner({ pid: null, startedAt: new Date(NOW - STAGING_TTL_MS - 1) }),
+    });
+    expect(reapOrphanedStaging(expired).reclaimed[0]?.reason).toBe('expired');
+  });
+
+  test('ignores directories that are not staging, rather than deleting them', () => {
+    const d = deps(
+      {},
+      {
+        dirs: [
+          '/tmp/something-else',
+          '/tmp/celilo-unrelated',
+          `/tmp/${STAGING_PREFIX}`, // prefix with no record id
+        ],
+      },
+    );
+    const report = reapOrphanedStaging(d);
+
+    expect(report.ignored).toHaveLength(3);
+    expect(report.reclaimed).toHaveLength(0);
+    expect(d.removed).toEqual([]);
+  });
+
+  test('an undeletable directory is reported as kept, not as reclaimed space', () => {
+    const path = stagingDirFor('locked-id');
+    const d = deps({ 'locked-id': null }, { unremovable: [path] });
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed).toHaveLength(0);
+    expect(report.kept).toEqual([path]);
+  });
+
+  test('one undeletable directory does not stop the rest of the pass', () => {
+    const locked = stagingDirFor('a-locked');
+    const d = deps({ 'a-locked': null, 'b-orphan': null }, { unremovable: [locked] });
+    const report = reapOrphanedStaging(d);
+
+    expect(report.reclaimed.map((r) => r.recordId)).toEqual(['b-orphan']);
+    expect(report.kept).toEqual([locked]);
+  });
+});

package/src/services/backup-staging.ts

@@ -0,0 +1,192 @@
+/**
+ * Reclaiming backup staging directories whose owner is gone.
+ *
+ * `backup-create.ts` assembles every envelope in a temp directory and removes
+ * it in a `finally`. That is correct and it is not enough: a `finally` does not
+ * run when the process is killed by a signal it cannot intercept — a dispatcher
+ * timeout, an OOM, an operator's Ctrl-C, a host reboot. Those are exactly the
+ * cases that strand the LARGEST directories, because the longer a backup has
+ * run the more it has written.
+ *
+ * Measured on celilo-mgr 2026-08-05: the scheduled sweep inherited the event
+ * bus's 60s default timeout against a forgejo backup that needs ~5.5 minutes,
+ * so every attempt was SIGTERMed at ~1.4 GB of staging, three times an hour,
+ * for days. 15 GB stranded in 26 hours, then 27 GB in the next 5.7. Nothing
+ * reclaimed it, because the only cleanup was the `finally` that never ran.
+ *
+ * So reclamation must not be a property of how a backup ends. This pass asks a
+ * different question — "is anyone still using this directory?" — and answers it
+ * from state that outlives the process.
+ *
+ * Identity comes free: a staging directory is named `celilo-backup-<record.id>`,
+ * so the directory names its own backup record. No lockfile, no marker, no
+ * second source of truth that could itself be stranded — and notably nothing
+ * written BY the process whose death is the problem.
+ *
+ * Dependencies are injected so the decision logic tests with no filesystem and
+ * no database.
+ */
+
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Every staging directory starts with this. The rest of the name is the record id. */
+export const STAGING_PREFIX = 'celilo-backup-';
+
+/**
+ * Where a backup record's staging lives. Single source of truth — `backup-create.ts`
+ * builds its temp dir from this so the reaper can never drift from the writer.
+ */
+export function stagingDirFor(recordId: string): string {
+  return join(tmpdir(), `${STAGING_PREFIX}${recordId}`);
+}
+
+/**
+ * How long an `in_progress` backup record may vouch for its staging before the
+ * directory is reclaimed regardless of what its pid appears to be doing.
+ *
+ * This is not redundancy on the liveness check — it is the only check that
+ * survives pid reuse, for the same reason `OPERATION_TTL_MS` exists in
+ * `module-operations.ts`. A pid is a recycled number: once the pid space wraps,
+ * a stale record's pid names an unrelated live process and the liveness probe
+ * reports "still running" forever, stranding the directory permanently.
+ *
+ * Six hours is comfortably longer than any real backup (the largest measured is
+ * ~5.5 minutes) and short enough that a wedged record costs one cycle rather
+ * than a filesystem.
+ */
+export const STAGING_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** What the backup record says about the process that owns a staging directory. */
+export interface StagingOwner {
+  status: string;
+  /** Null for records written before backups recorded their pid. */
+  pid: number | null;
+  startedAt: Date;
+}
+
+export interface ReapStagingDeps {
+  /** Absolute paths of every `celilo-backup-*` entry in the temp dir. */
+  listStagingDirs(): string[];
+  /** The backup record for this id, or null when it no longer exists. */
+  lookupOwner(recordId: string): StagingOwner | null;
+  isPidRunnable(pid: number): boolean;
+  remove(path: string): void;
+  now(): number;
+}
+
+export interface ReapedStaging {
+  path: string;
+  recordId: string;
+  /** Why it was reclaimable — surfaced so a sweep can explain itself. */
+  reason: 'record-absent' | 'record-terminal' | 'process-dead' | 'expired';
+}
+
+/**
+ * Written to a backup record reclaimed while it still claimed to be running.
+ *
+ * A record left `in_progress` after its process died misreports the system
+ * twice: `celilo backup list` shows work apparently underway, and the `backups`
+ * drift check can read a module as recently backed up when every attempt in
+ * fact died. Nine such rows were live on celilo-mgr while forgejo had no usable
+ * backup at all.
+ */
+export const ABANDONED_BACKUP_MESSAGE =
+  'abandoned — the backup process ended without recording an outcome';
+
+/**
+ * Whether reclaiming this directory also means its record was lying about
+ * being in progress.
+ *
+ * Only the two reasons reached from the `in_progress` branch qualify:
+ * `record-terminal` already has an outcome and `record-absent` has no row to
+ * correct.
+ */
+export function impliesAbandonedRecord(reason: ReapedStaging['reason']): boolean {
+  return reason === 'process-dead' || reason === 'expired';
+}
+
+export interface ReapStagingReport {
+  reclaimed: ReapedStaging[];
+  /** Left alone because a live backup is using it. */
+  kept: string[];
+  /** Names that did not look like staging at all. Never touched. */
+  ignored: string[];
+}
+
+/**
+ * Decide, for one staging directory, whether its owner is gone.
+ *
+ * Returns null when the directory must be left alone. Every branch that
+ * reclaims must be able to say why; "I could not prove it is alive" is not a
+ * reason to delete, which is why an unrecognised state keeps the directory.
+ */
+function reclaimReason(
+  owner: StagingOwner | null,
+  deps: Pick<ReapStagingDeps, 'isPidRunnable' | 'now'>,
+): ReapedStaging['reason'] | null {
+  // The record was deleted, or never committed. Nothing will ever finish this.
+  if (!owner) return 'record-absent';
+
+  // Completed or failed: the writer reached an ending and either cleaned up
+  // already (in which case we will not see the directory) or was killed after
+  // recording its outcome.
+  if (owner.status !== 'in_progress') return 'record-terminal';
+
+  const age = deps.now() - owner.startedAt.getTime();
+  if (age > STAGING_TTL_MS) return 'expired';
+
+  // A record from before backups carried a pid. Age is the only signal
+  // available, and it has not expired — leave it.
+  if (owner.pid === null) return null;
+
+  return deps.isPidRunnable(owner.pid) ? null : 'process-dead';
+}
+
+/**
+ * Reclaim every staging directory whose owning backup is no longer running.
+ *
+ * Conservative by construction: a directory is removed only when its owner is
+ * provably gone. A running backup — `in_progress` record, live pid, inside the
+ * TTL — is always kept, so a long-running or concurrent backup can never be
+ * destroyed by this pass.
+ *
+ * A name that is not `celilo-backup-<id>` is ignored rather than removed. This
+ * runs against a shared temp directory as a privileged user; deleting something
+ * it does not understand is not its job.
+ */
+export function reapOrphanedStaging(deps: ReapStagingDeps): ReapStagingReport {
+  const report: ReapStagingReport = { reclaimed: [], kept: [], ignored: [] };
+
+  for (const path of deps.listStagingDirs()) {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    if (!name.startsWith(STAGING_PREFIX)) {
+      report.ignored.push(path);
+      continue;
+    }
+
+    const recordId = name.slice(STAGING_PREFIX.length);
+    if (recordId.length === 0) {
+      report.ignored.push(path);
+      continue;
+    }
+
+    const reason = reclaimReason(deps.lookupOwner(recordId), deps);
+    if (!reason) {
+      report.kept.push(path);
+      continue;
+    }
+
+    // A directory that cannot be removed is not fatal: the next pass retries,
+    // and failing the whole sweep over one undeletable path would stop backups
+    // entirely. Treated as kept so the report never claims space it did not free.
+    try {
+      deps.remove(path);
+      report.reclaimed.push({ path, recordId, reason });
+    } catch {
+      report.kept.push(path);
+    }
+  }
+
+  return report;
+}