@celilo/cli 0.16.2 → 0.18.0

package/src/cli/index.ts

@@ -839,6 +839,9 @@ Subcommands:
   list                  List all configured storage destinations
   verify <storage-id>   Test storage connectivity and permissions
   set-default <id>      Set the default backup storage destination
+  set-path <id> <path>  Relocate a local destination to a new directory
+    Options:
+      --no-migrate      Change the path without moving existing archives
   remove <storage-id>   Remove a storage destination
     Options:
       --force           Skip confirmation prompts
@@ -860,6 +863,10 @@ Examples:
   # Set default destination
   celilo storage set-default local-backups
 
+  # Move a local destination (archives at the old path are moved too;
+  # if that path is gone, the change proceeds with nothing to migrate)
+  celilo storage set-path local-backups /var/lib/celilo/backups
+
   # Remove storage
   celilo storage remove local-backups --force
 
@@ -1836,6 +1843,11 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleStorageSetDefault(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'set-path') {
+      const { handleStorageSetPath } = await import('./commands/storage-set-path');
+      return handleStorageSetPath(parsed.args, parsed.flags);
+    }
+
     return {
       success: false,
       error: `Unknown storage subcommand: ${parsed.subcommand}\n\nRun "celilo storage --help" for usage`,

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

@@ -1,7 +1,9 @@
 import { describe, expect, test } from 'bun:test';
-import type { DriftFinding, SystemAuditReport } from '../../services/audit/types';
+import type { DriftCategory, DriftFinding, SystemAuditReport } from '../../services/audit/types';
 import {
+  ALL_CATEGORIES,
   type AuditTuiState,
+  CATEGORY_LABELS,
   groupFindings,
   initState,
   reducer,
@@ -244,3 +246,15 @@ describe('selectedFinding', () => {
     expect(selectedFinding(initState(report([])))).toBeNull();
   });
 });
+
+// ALL_CATEGORIES is a plain array, so the type system cannot require every
+// DriftCategory to appear in it — a new category compiles fine and then never
+// shows up in the TUI. CATEGORY_LABELS is a Record and IS exhaustive, so it is
+// the honest source of truth to compare against.
+describe('ALL_CATEGORIES covers every category', () => {
+  test('every labelled category is listed, and vice versa', () => {
+    expect([...ALL_CATEGORIES].sort()).toEqual(
+      (Object.keys(CATEGORY_LABELS) as DriftCategory[]).sort(),
+    );
+  });
+});

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

@@ -77,12 +77,15 @@ export const ALL_CATEGORIES: readonly 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',
 ];
 
@@ -95,12 +98,15 @@ export const CATEGORY_LABELS: Record<DriftCategory, string> = {
   module_configs: 'Module configs',
   health: 'Module health',
   backups: 'Backups',
+  abandoned_operations: 'Abandoned operations',
   undeployed_modules: 'Undeployed modules',
   unconfigured_modules: 'Unconfigured modules',
   services_credentials: 'Service credentials',
   secrets_decryptable: 'Secrets',
   services_reachable: 'Service reachability',
   machines_reachable: 'Machine reachability',
+  disk_space: 'Disk space',
+  transport_reads: 'Transport readability',
   trusted_sources: 'Trusted networks',
 };
 

package/src/cli/tui/audit-tui.test.tsx

@@ -35,7 +35,6 @@ const FIXTURE: SystemAuditReport = {
 };
 
 function strip(s: string): string {
-  // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping CSI escape sequences
   return s.replace(/\[[0-9;]*m/g, '');
 }
 

package/src/db/schema.ts

@@ -249,14 +249,31 @@ export const moduleBuilds = sqliteTable('module_builds', {
 });
 
 /**
- * Network zones type
- * - internal: Home network (192.168.0.0/24)
- * - dmz: Public-facing services in home lab (10.0.10.0/24)
- * - app: Internal application services (10.0.20.0/24)
- * - secure: Authentication and database services (10.0.30.0/24)
+ * Network zones — the DEFINED vocabulary, not the active set.
+ *
+ * A zone being listed here means celilo knows the name and will accept
+ * `network.<zone>.*` config for it. It does NOT mean the zone exists on a given
+ * fleet: per openspec/specs/progressive-zone-disclosure/spec.md, "deployable
+ * zones are those with a configured subnet", so a zone becomes REAL only when
+ * something declares `network.<zone>.subnet` — normally the module that supplies
+ * the network. Defining a zone here costs nothing and activates nothing.
+ *
+ * - internal: the semi-trusted LAN the management server sits on
+ * - dmz: public-facing services
+ * - app: internal application services
+ * - secure: authentication and database services
  * - secure-mgmt: celilo's own control plane (management server + management-plane
  *   modules). Outside the data-plane tier chain; reaches every tier by trust.
- * - external: Internet-hosted services (outside home network)
+ * - external: internet-hosted services — a cloud/VPS provider's network, NOT a
+ *   VPN. Addressed by the provider, which is why it is excluded from IPAM below.
+ * - control-plane-vpn: the ADMINISTRATIVE remote-access client subnet, activated
+ *   by the module that terminates the tunnel (`wireguard` writes
+ *   `network.control-plane-vpn.subnet`). Named for its purpose rather than its
+ *   technology because a fleet may run more than one VPN — a site-to-site link
+ *   or a user VPN is a different network with different trust, and `vpn` would
+ *   have been the wrong name to have to share. Distinct from `external` too:
+ *   that is someone else's cloud, this is a network the fleet's own firewall
+ *   holds a leg on and must translate for.
  */
 export const NETWORK_ZONES = [
   'internal',
@@ -265,6 +282,7 @@ export const NETWORK_ZONES = [
   'secure',
   'secure-mgmt',
   'external',
+  'control-plane-vpn',
 ] as const;
 
 /**
@@ -276,15 +294,36 @@ export const NETWORK_ZONES = [
 export type NetworkZone = (typeof NETWORK_ZONES)[number];
 
 /**
- * Zones an IP allocation or reservation can name: every NetworkZone except
- * `external`, whose systems are addressed by the provider, not by our IPAM.
+ * Zones an IP allocation or reservation can name: every NetworkZone whose
+ * addresses celilo hands out.
+ *
+ * Two are excluded, for the same underlying reason — somebody else is the
+ * address authority:
+ *   - `external`, whose systems are addressed by the cloud/VPS provider;
+ *   - `vpn`, whose client addresses are assigned by the module terminating the
+ *     tunnel. celilo allocating into that subnet would collide with the VPN
+ *     server's own assignments.
  *
  * Derived rather than hand-written for the same reason as NetworkZone above —
  * the previous hand-written union was copied into two column definitions and a
  * cast in machine-pool.ts, and the cast had already drifted (it was missing
  * `secure-mgmt`, and its comment claimed the only difference was `external`).
  */
-export type AllocatableZone = Exclude<NetworkZone, 'external'>;
+export type AllocatableZone = Exclude<NetworkZone, 'external' | 'control-plane-vpn'>;
+
+/** The zones whose addresses celilo hands out, as a runtime list. */
+export const ALLOCATABLE_ZONES: AllocatableZone[] = NETWORK_ZONES.filter(
+  (zone): zone is AllocatableZone => zone !== 'external' && zone !== 'control-plane-vpn',
+);
+
+/**
+ * Is this a zone celilo allocates addresses in? Use this rather than testing
+ * `zone !== 'external'` by hand — that check predates `vpn` and read as "the one
+ * externally-addressed zone" when there are now two.
+ */
+export function isAllocatableZone(zone: NetworkZone): zone is AllocatableZone {
+  return (ALLOCATABLE_ZONES as string[]).includes(zone);
+}
 
 /**
  * Container services table
@@ -679,6 +718,11 @@ export const backups = sqliteTable('backups', {
   status: text('status').$type<BackupStatus>().notNull().default('in_progress'),
   errorMessage: text('error_message'),
   name: text('name'), // optional human-readable name/annotation
+  // The process assembling this backup's staging directory. Lets the staging
+  // reaper (services/backup-staging.ts) tell a live backup from one whose
+  // process was killed before its `finally` could clean up. Nullable: rows
+  // written before this column existed have no pid and age out via the TTL.
+  pid: integer('pid'),
   startedAt: integer('started_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   completedAt: integer('completed_at', { mode: 'timestamp' }),
 });

package/src/hooks/capability-loader.ts

@@ -28,7 +28,14 @@ import type {
 } from '@celilo/capabilities';
 import { and, eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { capabilities, modules, secrets, systemConfig, webRoutes } from '../db/schema';
+import {
+  NETWORK_ZONES,
+  capabilities,
+  modules,
+  secrets,
+  systemConfig,
+  webRoutes,
+} from '../db/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
@@ -593,6 +600,7 @@ function buildCapabilityInterface(
           zoneTiers: zones?.zoneTiers ?? [],
           trustedSubnets: zones?.trustedSubnets ?? [],
           controlPlaneSubnet: zones?.controlPlaneSubnet,
+          frontedSubnets: zones?.frontedSubnets ?? [],
         },
         store,
         undefined, // no upstream — the chain path handles that
@@ -699,6 +707,22 @@ interface FirewallZones {
   trustedSubnets: string[];
   /** celilo's control-plane network, as a DESTINATION for trusted sources. */
   controlPlaneSubnet?: string;
+  /**
+   * Every declared zone subnet — read from
+   * `network.<zone>.subnet` across all of `NETWORK_ZONES`, not just the three
+   * data-plane tiers.
+   *
+   * A downstream firewall must translate for every network behind it, and the
+   * tiers are only the ones that happen to form the dmz→app→secure chain.
+   * `secure-mgmt` and the control-plane VPN are equally behind it and equally
+   * unroutable untranslated. Reading the canonical zone list rather than the tier
+   * list means declaring a zone's subnet is sufficient to get it translated — no
+   * module registration required.
+   *
+   * The egress network is NOT excluded here: the firewall derives that from its
+   * own routing table, so nothing on this side has to guess which zone it is.
+   */
+  frontedSubnets: string[];
 }
 
 /** The module that IS celilo's control plane; its network is what we trust. */
@@ -802,6 +826,10 @@ function loadFirewallZones(db: DbClient): FirewallZones {
     zoneTiers,
     trustedSubnets: loadTrustedSubnets(db).map((e) => e.subnet),
     controlPlaneSubnet: loadControlPlaneSubnet(db) ?? readZoneSubnet(db, 'internal'),
+    // Every zone celilo knows about, not the tier list — see the field doc.
+    frontedSubnets: NETWORK_ZONES.map((zone) => readZoneSubnet(db, zone)).filter(
+      (subnet): subnet is string => !!subnet,
+    ),
   };
 }
 
@@ -953,6 +981,7 @@ async function buildFirewallChain(
         zoneTiers: zones.zoneTiers,
         trustedSubnets: zones.trustedSubnets,
         controlPlaneSubnet: zones.controlPlaneSubnet,
+        frontedSubnets: zones.frontedSubnets,
       },
       store,
       currentUpstream,

package/src/ipam/allocator.ts

@@ -9,16 +9,26 @@ import type { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
 import type { DbClient } from '../db/client';
 import { ipAllocations, ipReservations, systemConfig, vmidReservations } from '../db/schema';
 import type { NewIpAllocation, NewIpReservation, NewVmidReservation } from '../db/schema';
+import { ALLOCATABLE_ZONES, type AllocatableZone } from '../db/schema';
 import type * as schema from '../db/schema';
 import { generateIPsInSubnet, isIPInRange, isInSubnet, stripCIDR } from './subnet-parser';
 
 // Type that accepts both database client and transaction
 type DbOrTransaction = BunSQLiteDatabase<typeof schema> | DbClient;
 
-/** Zones that support IPAM auto-allocation of VMID and container IP */
-export type IpamZone = 'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'internal';
+/**
+ * Zones that support IPAM auto-allocation of VMID and container IP.
+ *
+ * ALIASED to `AllocatableZone`, not hand-written. This was its own union
+ * (`'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'internal'`) that happened to
+ * agree with `AllocatableZone` — a fourth hand-maintained copy of the zone list,
+ * in a repo where three earlier copies had already drifted and left comments
+ * saying so. Deriving means a zone celilo stops allocating for (as `vpn` is,
+ * since the tunnel module assigns client addresses) cannot be missed here.
+ */
+export type IpamZone = AllocatableZone;
 
-const IPAM_ZONES: IpamZone[] = ['internal', 'dmz', 'app', 'secure', 'secure-mgmt'];
+const IPAM_ZONES: IpamZone[] = ALLOCATABLE_ZONES;
 
 /**
  * Infer which zone an IP address belongs to by checking configured zone subnets.

package/src/services/alerting/builtin-monitors.test.ts

@@ -27,6 +27,12 @@ describe('targetKindForCategory', () => {
     expect(targetKindForCategory('backups')).toBe('module');
   });
 
+  // Machine-scoped so suppression inherits the machine topology: an unreachable
+  // host suppresses its own disk alert instead of paging twice for one dead box.
+  test('disk_space is machine-scoped', () => {
+    expect(targetKindForCategory('disk_space')).toBe('machine');
+  });
+
   // Whole-system categories have no narrower subject to suppress against.
   test('unmapped category falls back to system', () => {
     expect(targetKindForCategory('cli_version')).toBe('system');
@@ -46,6 +52,42 @@ describe('severityForDriftSeverity', () => {
 });
 
 describe('failingKeysFromFindings', () => {
+  // Asserts the WHOLE key, not a prefix. A prefix-only assertion is exactly why
+  // #596 survived — machines_reachable emits a UUID where suppression expects a
+  // hostname, and `toContain('builtin:machines_reachable/machine:')` passes for
+  // both. This check must be pinned to the identifier itself.
+  test('disk_space keys on the hostname, in full', () => {
+    const keys = failingKeysFromFindings(
+      'disk_space',
+      [
+        finding({
+          category: 'disk_space',
+          code: 'disk_critical',
+          severity: 'blocked',
+          subject: 'celilo-mgr',
+          message: 'celilo-mgr: root filesystem 96% full',
+        }),
+      ],
+      'critical',
+    );
+
+    expect(keys).toHaveLength(1);
+    expect(keys[0]?.key).toBe('builtin:disk_space/machine:celilo-mgr');
+    expect(keys[0]?.severity).toBe('critical');
+  });
+
+  // An unmeasurable host records without paging.
+  test('an unmeasured disk downgrades to warning', () => {
+    const keys = failingKeysFromFindings(
+      'disk_space',
+      [finding({ category: 'disk_space', severity: 'todo', subject: 'iot' })],
+      'critical',
+    );
+
+    expect(keys[0]?.key).toBe('builtin:disk_space/machine:iot');
+    expect(keys[0]?.severity).toBe('warning');
+  });
+
   test('projects findings into builtin keys', () => {
     const keys = failingKeysFromFindings('machines_reachable', [finding()], 'critical');
     expect(keys).toEqual([

package/src/services/alerting/builtin-monitors.ts

@@ -24,9 +24,12 @@ import { type FailingKey, builtinAlertKey } from './keys';
  */
 const TARGET_KIND_BY_CATEGORY: Partial<Record<DriftCategory, string>> = {
   machines_reachable: 'machine',
+  disk_space: 'machine',
+  transport_reads: 'module',
   services_reachable: 'service',
   services_credentials: 'service',
   backups: 'module',
+  abandoned_operations: 'module',
   health: 'module',
   module_versions: 'module',
   module_configs: 'module',

package/src/services/alerting/builtin-source.ts

@@ -13,16 +13,21 @@
  */
 
 import type { DbClient } from '../../db/client';
+import { auditAbandonedOperations, loadAbandonedOperations } from '../audit/abandoned-operations';
 import { loadBackupAuditInfo } from '../audit/backup-source';
 import { auditBackups } from '../audit/backups';
+import { auditDiskSpace } from '../audit/disk-space';
 import { auditMachinesReachable } from '../audit/machines-reachable';
 import type { DriftCategory, DriftFinding } from '../audit/types';
+import { probeDiskUsage } from '../disk-probe';
 import { probeMachines } from '../machine-probe';
 
 /** Categories a monitor can currently schedule. */
 export const SCHEDULABLE_BUILTIN_CHECKS: readonly DriftCategory[] = [
   'machines_reachable',
   'backups',
+  'disk_space',
+  'abandoned_operations',
 ];
 
 export function isSchedulableBuiltin(category: string): category is DriftCategory {
@@ -37,12 +42,22 @@ export async function runBuiltinCheckForMonitor(
     return auditMachinesReachable({ results: await probeMachines() });
   }
 
+  // Same shape as machines_reachable — one SSH round trip per machine, bounded
+  // — but it MEASURES the local box rather than exempting it. See disk-probe.ts.
+  if (category === 'disk_space') {
+    return auditDiskSpace({ results: await probeDiskUsage() });
+  }
+
   // Local DB reads only — cheap enough to run on every sweep, which is
   // the whole reason this category is schedulable and most are not.
   if (category === 'backups') {
     return auditBackups({ modules: loadBackupAuditInfo(db) });
   }
 
+  if (category === 'abandoned_operations') {
+    return auditAbandonedOperations({ records: loadAbandonedOperations(db) });
+  }
+
   throw new Error(
     `Built-in check "${category}" is not schedulable yet. Schedulable: ${SCHEDULABLE_BUILTIN_CHECKS.join(', ')}.`,
   );

package/src/services/alerting/inbound-poller.test.ts

@@ -7,7 +7,12 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Route, alerts, modules, monitors, notificationDeliveries } from '../../db/schema';
 import { setupTestDatabase } from '../../test-utils/setup-test-db';
-import { type InboundPollDeps, pollInbound, transportsWithRoutes } from './inbound-poller';
+import {
+  type InboundPollDeps,
+  type TransportReadRecord,
+  pollInbound,
+  transportsWithRoutes,
+} from './inbound-poller';
 import { moduleCheckAlertKey } from './keys';
 import { createPerson, createRoute } from './people';
 import { mintDelivery } from './tokens';
@@ -386,6 +391,63 @@ describe('pollInbound', () => {
     expect(ackedBy()).toBe(peterRoute.personId);
   });
 
+  // The gap this closes. The ONLY per-transport state celilo persisted was the
+  // cursor, and writeCursor early-returns when there is no cursor — which a
+  // failed read never produces. So the store could not REPRESENT a failure, and
+  // "unreadable for a week" and "nobody replied for a week" left identical
+  // traces (#501).
+  describe('recording what each read attempt produced', () => {
+    const records: Array<[string, TransportReadRecord]> = [];
+    const recording = (over: Partial<InboundPollDeps> = {}) =>
+      deps([], { recordRead: (t, r) => records.push([t, r]), ...over });
+
+    beforeEach(() => {
+      records.length = 0;
+    });
+
+    test('a FAILED read is recorded — the case the cursor could never express', async () => {
+      await pollInbound(
+        db,
+        recording({ receiveFrom: async () => ({ status: 'failed', error: 'connection refused' }) }),
+      );
+      expect(records).toHaveLength(1);
+      expect(records[0][0]).toBe('signal');
+      expect(records[0][1]).toMatchObject({ outcome: 'failed', error: 'connection refused' });
+    });
+
+    test('a successful read is recorded with how many messages it returned', async () => {
+      await pollInbound(
+        db,
+        deps([inbound(PETER, 'hello')], { recordRead: (t, r) => records.push([t, r]) }),
+      );
+      expect(records[0][1]).toMatchObject({ outcome: 'received', messages: 1 });
+    });
+
+    // Zero messages is not failure. Conflating them is the original bug.
+    test('an empty but successful read records received, not failed', async () => {
+      await pollInbound(db, recording());
+      expect(records[0][1]).toMatchObject({ outcome: 'received', messages: 0 });
+    });
+
+    test('a unidirectional transport is recorded as such', async () => {
+      await pollInbound(db, recording({ receiveFrom: async () => ({ status: 'unidirectional' }) }));
+      expect(records[0][1].outcome).toBe('unidirectional');
+    });
+
+    // Every attempt, not just interesting ones — a gap in the record would be
+    // read as "nothing happened".
+    test('every attempt is recorded, and carries when it happened', async () => {
+      await pollInbound(db, recording());
+      expect(records[0][1].at).toBe(NOW.toISOString());
+    });
+
+    // Optional dep: a caller that does not persist must still poll.
+    test('polling works with no recorder attached', async () => {
+      const report = await pollInbound(db, deps([]));
+      expect(report.transportsPolled).toBe(1);
+    });
+  });
+
   test('a route pointing at a transport nobody uses is not polled', () => {
     db.delete(alerts).run();
     expect(transportsWithRoutes(db)).toEqual(['signal']);

package/src/services/alerting/inbound-poller.ts

@@ -44,6 +44,35 @@ export interface TransportFailure {
   error: string;
 }
 
+/**
+ * The outcome of one attempt to read a transport, as recorded for later.
+ *
+ * Written on EVERY attempt, including failures — which is the whole point. The
+ * only per-transport state celilo persisted before this was the cursor, and a
+ * failed read produces no cursor, so `writeCursor` returned early and nothing
+ * was written. The store could not REPRESENT a failure, so an absence of
+ * recorded failures was never evidence there had been none: a transport that
+ * had not been readable for a week looked identical to one nobody had replied
+ * on (#501).
+ */
+export interface TransportReadRecord {
+  /** When the attempt happened, ISO-8601. */
+  at: string;
+  outcome: 'received' | 'unidirectional' | 'failed';
+  /** Present only when `failed`. */
+  error?: string;
+  /** How many messages the read returned. Zero is not the same as failure. */
+  messages: number;
+  /**
+   * When a read last SUCCEEDED, carried forward across failures.
+   *
+   * This is the field that answers the question the old state could not: a
+   * transport reporting "0 messages" for a week and one that has not been
+   * readable for a week are the same picture until you can see this.
+   */
+  lastSuccessAt?: string;
+}
+
 /** A message that was read but not acted on, and why. */
 export interface UnheardMessage {
   senderAddress: string;
@@ -65,6 +94,13 @@ export interface InboundPollDeps {
   /** Persisted receive cursor per transport. */
   readCursor(transportModuleId: string): string | null;
   writeCursor(transportModuleId: string, cursor: string | null): void;
+  /**
+   * Record what one read attempt produced. Called for EVERY attempt — a failed
+   * read must leave a trace, or "we could not read this transport" stays
+   * indistinguishable from "nobody replied". Optional so a caller that does not
+   * care (tests, one-off invocations) need not supply it.
+   */
+  recordRead?(transportModuleId: string, record: TransportReadRecord): void;
   now(): Date;
   /**
    * Transport for a route, so an ack can be broadcast to everyone else paged.
@@ -131,6 +167,12 @@ export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<
   for (const transportId of transportsWithRoutes(db)) {
     const received = await deps.receiveFrom(transportId, deps.readCursor(transportId));
     report.transportsPolled++;
+    deps.recordRead?.(transportId, {
+      at: deps.now().toISOString(),
+      outcome: received.status,
+      ...(received.status === 'failed' ? { error: received.error } : {}),
+      messages: received.status === 'received' ? received.messages.length : 0,
+    });
     // One dead transport must not stop the others being read — but it is
     // RECORDED rather than skipped in silence, because "cannot read" and
     // "nothing to read" are the two things an operator most needs to tell

package/src/services/alerting/read-records.ts

@@ -0,0 +1,85 @@
+/**
+ * The per-transport record of whether celilo can still READ replies.
+ *
+ * Extracted from the poll command because it now has two readers: the poller
+ * writes it, and the audit asserts on it. Keeping the key format private to the
+ * writer would have meant the audit re-deriving a string literal — the sort of
+ * duplication that silently stops matching.
+ *
+ * The shape it stores is the point. celilo's only per-transport state used to
+ * be the receive cursor, and `writeCursor` returns early when there is no
+ * cursor — which a failed read never produces. So the store could not
+ * REPRESENT a failure, and "unreadable since Tuesday" left exactly the same
+ * trace as "nobody replied since Tuesday" (#501).
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { systemConfig } from '../../db/schema';
+import { type TransportReadRecord, transportsWithRoutes } from './inbound-poller';
+
+const READ_PREFIX = 'alerting.last_read.';
+
+export function readLastRead(db: DbClient, transportModuleId: string): TransportReadRecord | null {
+  const row = db
+    .select()
+    .from(systemConfig)
+    .where(eq(systemConfig.key, `${READ_PREFIX}${transportModuleId}`))
+    .get();
+  if (!row?.value) return null;
+  try {
+    return JSON.parse(row.value) as TransportReadRecord;
+  } catch {
+    // A malformed row must not read as "never succeeded" — that would invent a
+    // fact and page someone about it.
+    return null;
+  }
+}
+
+/**
+ * Record one attempt, carrying the last SUCCESS forward.
+ *
+ * Deliberately has no counterpart to `writeCursor`'s early return: a failure
+ * that writes nothing is why this record did not exist before. Carrying the
+ * success forward is what turns a log into an answer — a run of failures must
+ * not erase when the transport last actually worked.
+ */
+export function writeLastRead(
+  db: DbClient,
+  transportModuleId: string,
+  record: TransportReadRecord,
+): void {
+  const key = `${READ_PREFIX}${transportModuleId}`;
+  const previous = readLastRead(db, transportModuleId);
+  const lastSuccessAt =
+    record.outcome === 'received' ? record.at : (previous?.lastSuccessAt ?? undefined);
+  const value = JSON.stringify({ ...record, ...(lastSuccessAt ? { lastSuccessAt } : {}) });
+
+  const existing = db.select().from(systemConfig).where(eq(systemConfig.key, key)).get();
+  if (existing) {
+    db.update(systemConfig).set({ value }).where(eq(systemConfig.key, key)).run();
+  } else {
+    db.insert(systemConfig)
+      .values({ key, value, description: `Last inbound read attempt for ${transportModuleId}` })
+      .run();
+  }
+}
+
+export interface TransportReadStatus {
+  transportModuleId: string;
+  last: TransportReadRecord | null;
+}
+
+/**
+ * Read state for every transport that has a route pointing at it.
+ *
+ * Scoped to transports with routes on purpose: a transport nobody is routed to
+ * cannot fail to deliver anyone's acknowledgement, and paging about it would be
+ * noise that trains an operator to ignore this check.
+ */
+export function readAllTransportStatuses(db: DbClient): TransportReadStatus[] {
+  return transportsWithRoutes(db).map((transportModuleId) => ({
+    transportModuleId,
+    last: readLastRead(db, transportModuleId),
+  }));
+}