@celilo/cli 0.16.1 → 0.17.0

package/CELILO_SUBSYSTEMS.md

@@ -197,6 +197,7 @@ Creation, scheduling and freshness. A module declares an `on_backup` hook and a
 - **The sweep** — `apps/celilo/src/services/backup-sweep.ts` — `runBackupSweep` (the pass that makes backups run by themselves: for each eligible module, is its declared cadence due → back it up → apply declared retention) + `ensureBackupSweepSubscriber`. Driven by `celilo backup sweep` on `timer.tick.1h` — the coarsest tick that can still serve an `hourly` cadence. Armed automatically: `registerModuleSubscriptions` registers the subscriber for any module declaring an `on_backup` hook, so it appears on install or `module update`. A run refused by the in-flight operation lock is a skip retried next tick, never a failure.
 - **Freshness audit** — `apps/celilo/src/services/audit/backups.ts` (`auditBackups`) — `backup_missing` / `backup_stale` drift findings against the same declared cadence.
 - **CLI** — `apps/celilo/src/cli/commands/` — `backup-sweep.ts`, `backup-create.ts` (also `celilo module backup`), `backup-list.ts`, `backup-restore.ts`, `backup-prune.ts`, `backup-delete.ts`, `backup-import.ts`, `backup-pull.ts`, `backup-name.ts`.
+- **Storage destinations CLI** — `storage-add-local.ts`, `storage-add-s3.ts`, `storage-list.ts`, `storage-verify.ts`, `storage-set-default.ts`, `storage-set-path.ts` (relocate a local destination, migrating existing archives unless `--no-migrate`), `storage-remove.ts`. Any credential change goes through `updateStorageCredentials` in `backup-storage.ts`, which clears the verification stamp — a `✓ Verified` must never describe a destination it was not measured against (#566).
 
 ## Persistence
 
@@ -218,7 +219,8 @@ Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <h
 - **Access control** — `apps/celilo/src/services/api-access.ts` — `grantPrincipal`, `isAuthorized` (deny-by-default, `command:subcommand` grants), `renderAuthorizedKeys`. Table: `api_principals` (`apps/celilo/src/db/schema.ts`). CLI: `apps/celilo/src/cli/commands/api.ts` (`api grant|list|revoke|authorized-keys|key new`).
 - **Mid-run interview bridge (`kind:daemon` responder)** — `apps/celilo/src/services/remote-responder.ts` — `startRemoteResponder` bridges bus `interview.required.*` ↔ wire.
 - **Server provisioning** — the `celilo-bootstrap` deb (`packaging/celilo-bootstrap/scripts/postinst`) creates the non-root `celilo-api` landing account + sshd; membership in the `celilo` group + `/etc/sudoers.d/celilo` (`!use_pty`) gives api-serve DB access via the wrapper's sudo-drop.
-- **Self-upgrade (apt)** — `celilo apt-upgrade` (`apps/celilo/src/cli/commands/apt-upgrade.ts`) upgrades the deb-installed `celilo`/`celilo-bootstrap` packages (`apt-get update` → `--only-upgrade install`) then spawns a fresh `celilo system migrate` (ISS-0100). It's the RW target behind the MCP's registry-derived `celilo_apt_upgrade` tool; the celilo user's two apt invocations are scoped-sudo'd by `/etc/sudoers.d/celilo-apt-upgrade`, shipped by `celilo-bootstrap`.
+- **Self-upgrade (apt)** — `celilo apt-upgrade` (`apps/celilo/src/cli/commands/apt-upgrade.ts`) upgrades the deb-installed `celilo`/`celilo-bootstrap` packages (`apt-get update` → `--only-upgrade install`) then spawns a fresh `celilo system migrate` (ISS-0100). It's the RW target behind the MCP's registry-derived `celilo_apt_upgrade` tool; the celilo user's two apt invocations are scoped-sudo'd by `/etc/sudoers.d/celilo-apt-upgrade`, shipped by `celilo-bootstrap`. **This upgrades celilo ITSELF — not the modules it manages. For those, see Module auto-upgrade below; the two are routinely confused.**
+- **Module auto-upgrade (registry-poll CD)** — the *pull* half of continuous deployment: celilo-mgr polls the registry and upgrades opted-in modules unattended. Spec: `openspec/specs/module-auto-upgrade/spec.md`. Entry points: `apps/celilo/src/cli/commands/module-upgrade.ts` — `runRegistryPoll` (the `--poll` path), `selectPollTargets` (pure: `autoUpgrade && latest && change ∉ {up-to-date, ahead}`), `upgradeOneModule` (update → backup → deploy → verify), `needsPreUpgradeBackup`, `pickAutoUpgrade`/`pickUpgradePolicy` (both fail closed/safe); `classifyVersionChange` in `module-update.ts` (treats a registry `+N` revision as a patch); `resolveDeployPosture` in `apps/celilo/src/services/deploy-posture.ts`. Trigger: celilo-mgmt's `registry-poll` subscription (`modules/celilo-mgmt/manifest.yml`) on `timer.tick.15m` with handler **`celilo module upgrade --poll`** — the flag is REQUIRED, since the dispatcher appends the event id positionally and a bare handler would consume it as the optional module name (silent: 3108 deliveries, 0 successes). Operator controls are framework config keys settable on ANY module (`FRAMEWORK_CONFIG_KEYS` in `module-config.ts`): `auto_upgrade` (opt-in, default false) and `upgrade_policy` (`by-semver`|`always-safe`|`always-fast`), validated at set time because both readers fail open. ⚠️ `always-safe` guarantees safe *posture*, NOT a backup — `needsPreUpgradeBackup` also requires the TARGET manifest to declare an `on_backup` hook, else it warns and proceeds. Confirm a data-bearing module declares `on_backup` before enabling `auto_upgrade` on it. The *build* half (app CI publishing a `.netapp` on merge) is not yet shipped — `openspec/changes/build-bus-poll-cd`.
 - **MCP service (`@celilo/mcp`)** — `packages/mcp/src/` — an operator-facing stdio MCP server (official `@modelcontextprotocol/sdk`, bin `celilo-mcp`) that drives a remote celilo server over the Remote API for an AI client. Two-item config (`config.ts`: `server` + `defaultUser`, env or `~/.config/celilo-mcp/config.json`). Dual-principal auth (`auth.ts`: `celilo-mcp auth setup` enrolls read-only `celilo-mcp-ro` + full `celilo-mcp-rw` ed25519 keypairs, prints the exact `celilo api grant` lines the operator runs server-side). Transport (`transport.ts`): reuses `@celilo/core` `runRemoteClient`, selecting the principal by `ssh -i <key>` and capturing structured output. Tool surface is generated LIVE from the server's command registry — `registry-fetch.ts` fetches `celilo commands --json` (+ `service list --json` for configured providers) over the RO principal on connect; `tools-from-registry.ts` (pure) projects that into one tool per runnable leaf, grouped by top-level command (`celilo_module_*`, `celilo_proxmox_*`, …), each with a Zod input schema from the leaf's args/flags and a read/write tag → RO/RW routing, plus a generic `celilo_run` escape hatch. Auto-detect hides provider-gated groups (e.g. `celilo_proxmox_*` until a Proxmox service is configured) and re-detects on a timer, emitting `notifications/tools/list_changed` when the surface changes. Coverage gate (`tests/coverage.test.ts`) asserts every registry leaf maps to a tool. Composite RO troubleshooting tools (`troubleshoot.ts` pure correlation + `troubleshoot-tools.ts` thin adapters): `celilo_assess_module <id>` and `celilo_fleet_status` correlate `celilo audit --json` (the drift backbone) with the `module list --json` roster into a per-module / fleet-wide verdict. Design: `openspec/changes/celilo-mcp-service/proposal.md`. (Distinct from the dev/ops `@celilo/mcp-server` below.)
 
 ## E2E simulation
@@ -227,4 +229,5 @@ Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <h
 - **Run wrapper** — `infra/scripts/cele2e-run.sh` lives in the separate `infra/` clone, **not** in this repo. See the cele2e section of the repo-root `CLAUDE.md` for the operator workflow.
 - **Signal simulators** — three containers, three jobs. `docker/Dockerfile.signal-cli` runs the REAL unlinked daemon (`network().withSignalCli()`, reachable at `signal-cli.lab`) so `e2e/tests/signal-contract.test.ts` can re-check celilo's understanding of the JSON-RPC surface against the actual binary — the pebble pattern. `docker/Dockerfile.signal-sim` runs `simulators/signal-cli/server.ts` (`withSignalSim()`, `signal-sim.lab`), the drivable stand-in with a control surface (`/_control/inbound`, `/_control/sent`, `/_control/unlink`). `/_control/inbound` from the LINKED account's own number emits a `syncMessage.sentMessage` transcript rather than a `dataMessage`, because that is the only shape the real daemon delivers a note-to-self in — and a note-to-self is what every reply is in the default single-operator setup (#460). `docker/Dockerfile.signal-release` (`withSignalRelease()`, `signal-release.lab`) serves the signal-cli release tarball so the module's deploy-time download resolves inside the sealed network — the download is served, never skipped. The libsignal aarch64 native is compiled at `build-infra` time from the module's own recipe (`packages/e2e/scripts/stage-libsignal.ts` → `modules/signal/build/`) and staged into the apt-repo pool, so the recipe is exercised for real on every rebuild while the deploy stays fast and the network stays sealed.
 - **Public-boundary NAT model** — `packages/e2e/config/routing/` — exactly ONE NAT sits between the fleet and the simulated internet: the customer firewall (`fw-main` in `direct-internet`, `fw-isp` in the two-layer default), which MASQUERADEs to `100.100.0.100`. The ISP edge `fw-ext` ROUTES the customer's `100.100.0.0/24` and must never re-NAT it (`-s 100.100.0.0/24 -j RETURN` ahead of its MASQUERADE) — an ISP does not NAT a subscriber that already holds a public address. This is load-bearing, not cosmetic: Namecheap-style DDNS registers the SOURCE address when the caller omits `ip=`, which is how celilo registers public names since #464/#466, so a second NAT here publishes the simulator's own address for every public hostname and quietly breaks ACME, inbound reach, and seeded apex records. Constants: `externalWanIp()` / `externalWanSubnet()` in `src/types.ts`. The corollary: every simulator on `internet-external` must default-route via fw-ext (`100.64.0.1`) so it can reply to the customer's public address — Docker's bridge gateway has no path across networks. `config/routing/public-sim-entrypoint.sh` is the shared two-liner; the DNS hierarchy, pebble, isitup and celilo-website-sim already carried it, and npm-registry / registry / apt-repo / minio / cpanel-host only appeared to work because the double NAT put fw-ext's on-link address in the source field.
+- **Simulated address plan** — `packages/e2e/src/types.ts` — `SIM_PRIVATE_SUPERNET` (`10.226.0.0/16`), `zoneIp(zone, host)`, `ZONE_SUBNETS`, `ZONE_GATEWAYS`. Every simulated PRIVATE zone is derived from this one table; the compose generator, `zone-classifier.ts` and the harness's `system init` all read it, so renumbering the whole sim is a one-line change. The sim deliberately does NOT reuse a real fleet's zone /24s (#539): the previous plan was byte-identical to production's, so a stack leaked on celilo's own forgejo-builder — which lives in the real dmz — claimed the builder's own subnet and blackholed every containerized CI job's route to the forge for ~135s. Teardown cannot prevent that (a SIGKILL runs no handler), so the addresses moved instead; the second, better reason is that a suite which only passes on production's exact octets is asserting one site's address plan rather than celilo's behaviour. `src/address-plan.test.ts` is the recurrence gate — it fails if a zone leaves the supernet, or if any retired fleet prefix reappears anywhere in `packages/e2e`, `e2e/tests` or `modules/*/e2e`.
 - **MCP server (agent-driven e2e)** — `packages/mcp-server/src/index.ts` — stdio MCP server exposing `start_run`/`run_status`/`run_result`/`stop_run` (detached cele2e runs read off the event bus, no ANSI scraping) + `env_check` (docker VM, run-lock, shared-infra, mgmt image CLI version, netapps). Dev/ops tool, `private`, not shipped to consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -59,8 +59,8 @@
     "@aws-sdk/client-s3": "^3.1024.0",
     "@celilo/capabilities": "^0.9.1",
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/core": "^0.3.0",
-    "@celilo/event-bus": "^0.1.9",
+    "@celilo/core": "^0.3.1",
+    "@celilo/event-bus": "^0.1.10",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/cli/commands/alerts-poll.ts

@@ -17,6 +17,7 @@ import { systemConfig } from '../../db/schema';
 import { makeReceiver, pollInbound } from '../../services/alerting/inbound-poller';
 import { startNotificationResponder } from '../../services/alerting/notification-responder';
 import { listRoutes } from '../../services/alerting/people';
+import { readLastRead, writeLastRead } from '../../services/alerting/read-records';
 import { loadNotificationTransport } from '../../services/alerting/transport-loader';
 import type { CommandResult } from '../types';
 
@@ -52,6 +53,26 @@ function writeCursor(
   }
 }
 
+/**
+ * " (last read OK 3h ago)" or " (never read successfully)".
+ *
+ * Appended to a read failure because the failure alone does not say how bad it
+ * is. One failed poll is a blip; a transport that has not been readable since
+ * Tuesday is an outage nobody was told about, and those two produced identical
+ * output until this record existed.
+ */
+function sinceLastSuccess(db: ReturnType<typeof getDb>, transportModuleId: string): string {
+  const last = readLastRead(db, transportModuleId)?.lastSuccessAt;
+  if (!last) return ' (never read successfully)';
+  const ms = Date.now() - new Date(last).getTime();
+  const mins = Math.floor(ms / 60_000);
+  if (mins < 60) return ` (last read OK ${mins}m ago)`;
+  const hours = Math.floor(mins / 60);
+  return hours < 48
+    ? ` (last read OK ${hours}h ago)`
+    : ` (last read OK ${Math.floor(hours / 24)}d ago)`;
+}
+
 export async function handleAlertsPoll(
   flags: Record<string, string | boolean> = {},
 ): Promise<CommandResult> {
@@ -97,6 +118,7 @@ export async function handleAlertsPoll(
     receiveFrom: makeReceiver(db),
     readCursor: (t) => readCursor(db, t),
     writeCursor: (t, c) => writeCursor(db, t, c),
+    recordRead: (t, r) => writeLastRead(db, t, r),
     now: () => new Date(),
     transportFor: (route) => loadNotificationTransport(db, route.transportModuleId),
     answerInterview: (eventId, value) => responder.answer(eventId, value),
@@ -122,7 +144,10 @@ export async function handleAlertsPoll(
   // an operator has no way to tell which — the ambiguity that made the Signal
   // ack path take a week to diagnose.
   const detail = [
-    ...report.failures.map((f) => `${f.transportModuleId} COULD NOT BE READ: ${f.error}`),
+    ...report.failures.map(
+      (f) =>
+        `${f.transportModuleId} COULD NOT BE READ: ${f.error}${sinceLastSuccess(db, f.transportModuleId)}`,
+    ),
     ...report.unheard.map((u) => `not heard from ${u.senderAddress}: ${u.reason}`),
     ...askErrors,
   ];

package/src/cli/commands/storage-set-path.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Tests for `storage set-path`.
+ *
+ * The motivating case (#566) is celilo-mgr: `local-backups` points at
+ * `/Users/pbanka/hobby/backups/celilo-backups/`, a macOS path that came
+ * across when the database was restored onto a Linux host. The directory
+ * does not exist there. Relocating must therefore succeed with nothing
+ * migrated — not error, and not claim files were moved — and must not
+ * carry the four-month-old `✓ Verified` stamp onto the new path.
+ *
+ * Isolation: CELILO_DB_PATH / CELILO_DATA_DIR are set before the SUT is
+ * imported, so nothing touches the production database.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testRoot = mkdtempSync(join(tmpdir(), 'celilo-setpath-'));
+process.env.CELILO_DB_PATH = join(testRoot, 'celilo.db');
+process.env.CELILO_DATA_DIR = join(testRoot, 'data');
+
+const {
+  addBackupStorage,
+  getBackupStorageByStorageId,
+  getStorageCredentials,
+  updateStorageCredentials,
+} = await import('../../services/backup-storage');
+const { handleStorageSetPath, inspectSourceDir, planRelocation, resolveTargetPath } = await import(
+  './storage-set-path'
+);
+
+afterAll(() => {
+  rmSync(testRoot, { recursive: true, force: true });
+});
+
+describe('planRelocation (pure)', () => {
+  const base = { sourceDir: '/old/celilo-backups', targetDir: '/new/celilo-backups' };
+
+  test('migrates when the source has files', () => {
+    const plan = planRelocation({ ...base, sourceState: 'populated', migrateRequested: true });
+    expect(plan.migrate).toBe(true);
+    expect(plan.note).toContain('Migrating archives');
+  });
+
+  test('PRODUCTION CASE: source missing — skips migration, says so, does not error', () => {
+    const plan = planRelocation({ ...base, sourceState: 'missing', migrateRequested: true });
+    expect(plan.migrate).toBe(false);
+    expect(plan.note).toContain('does not exist');
+    expect(plan.note).toContain('nothing to migrate');
+  });
+
+  test('source unreadable — skips migration and says nothing was moved', () => {
+    const plan = planRelocation({ ...base, sourceState: 'unreadable', migrateRequested: true });
+    expect(plan.migrate).toBe(false);
+    expect(plan.note).toContain('not readable');
+  });
+
+  test('source empty — skips migration', () => {
+    const plan = planRelocation({ ...base, sourceState: 'empty', migrateRequested: true });
+    expect(plan.migrate).toBe(false);
+    expect(plan.note).toContain('empty');
+  });
+
+  test('--no-migrate wins even over a populated source', () => {
+    const plan = planRelocation({ ...base, sourceState: 'populated', migrateRequested: false });
+    expect(plan.migrate).toBe(false);
+    expect(plan.note).toContain('--no-migrate');
+  });
+});
+
+describe('resolveTargetPath (pure)', () => {
+  test('rejects a path identical to the current one', () => {
+    const result = resolveTargetPath('/var/backups', '/var/backups/');
+    expect(result).toMatchObject({ success: false });
+  });
+
+  test('preserves a path containing a space', () => {
+    const result = resolveTargetPath('/tmp/back ups/celilo', '/somewhere/else');
+    expect(result).toEqual({ path: '/tmp/back ups/celilo' });
+  });
+
+  test('expands a leading tilde', () => {
+    const result = resolveTargetPath('~/backups', '/somewhere/else');
+    expect(result).toMatchObject({ path: join(homedir(), 'backups') });
+  });
+});
+
+describe('inspectSourceDir', () => {
+  test('missing directory reports missing, not unreadable', () => {
+    expect(inspectSourceDir(join(testRoot, 'no-such-dir'))).toBe('missing');
+  });
+
+  test('empty directory reports empty', () => {
+    const dir = join(testRoot, 'empty-dir');
+    mkdirSync(dir, { recursive: true });
+    expect(inspectSourceDir(dir)).toBe('empty');
+  });
+
+  test('directory with files reports populated', () => {
+    const dir = join(testRoot, 'full-dir');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'a.backup'), 'x');
+    expect(inspectSourceDir(dir)).toBe('populated');
+  });
+
+  test('unreadable directory reports unreadable, not missing', () => {
+    const parent = join(testRoot, 'locked');
+    const dir = join(parent, 'celilo-backups');
+    mkdirSync(dir, { recursive: true });
+    chmodSync(parent, 0o000);
+    try {
+      expect(inspectSourceDir(dir)).toBe('unreadable');
+    } finally {
+      chmodSync(parent, 0o700);
+    }
+  });
+});
+
+describe('updateStorageCredentials', () => {
+  test('clears the verification stamp, so a stale ✓ never survives a credential change (#566)', async () => {
+    const storage = await addBackupStorage({
+      name: 'Stamp Backups',
+      providerName: 'local',
+      credentials: { path: '/Users/nobody/old' },
+    });
+
+    const { getDb } = await import('../../db/client');
+    const { backupStorages } = await import('../../db/schema');
+    const { eq } = await import('drizzle-orm');
+    getDb()
+      .update(backupStorages)
+      .set({ verified: true, verifiedAt: new Date('2026-04-08T02:24:43.000Z') })
+      .where(eq(backupStorages.id, storage.id))
+      .run();
+
+    await updateStorageCredentials(storage.id, { path: '/var/lib/celilo/backups' });
+
+    // Asserted WITHOUT a follow-up verify: even if celilo dies between
+    // the path change and re-verification, the row must not still claim
+    // the destination was verified.
+    const after = getBackupStorageByStorageId(storage.storageId);
+    expect(after?.verified).toBe(false);
+    expect(after?.verifiedAt).toBeNull();
+  });
+});
+
+describe('handleStorageSetPath (end to end, isolated DB)', () => {
+  test('PRODUCTION CASE: current path does not exist — path changes, nothing migrated, re-verified against the new path', async () => {
+    const storage = await addBackupStorage({
+      name: 'Ghost Backups',
+      providerName: 'local',
+      credentials: { path: '/Users/nobody/hobby/backups' },
+    });
+
+    // Simulate the stale stamp: the row says Verified from a host that
+    // no longer exists.
+    const { getDb } = await import('../../db/client');
+    const { backupStorages } = await import('../../db/schema');
+    const { eq } = await import('drizzle-orm');
+    getDb()
+      .update(backupStorages)
+      .set({ verified: true, verifiedAt: new Date('2026-04-08T02:24:43.000Z') })
+      .where(eq(backupStorages.id, storage.id))
+      .run();
+
+    const newPath = join(testRoot, 'relocated');
+    const result = await handleStorageSetPath([storage.storageId, newPath]);
+
+    expect(result.success).toBe(true);
+
+    const creds = await getStorageCredentials(storage.id);
+    expect(creds).toMatchObject({ path: newPath });
+
+    // The stamp must describe the NEW path, not the dead one.
+    const after = getBackupStorageByStorageId(storage.storageId);
+    expect(after?.verified).toBe(true);
+    expect(after?.verifiedAt?.getTime()).toBeGreaterThan(
+      new Date('2026-04-08T02:24:43.000Z').getTime(),
+    );
+  });
+
+  test('moves existing archives to the new location', async () => {
+    const oldPath = join(testRoot, 'movable-old');
+    const newPath = join(testRoot, 'movable-new');
+    mkdirSync(join(oldPath, 'celilo-backups', '2026-08-01'), { recursive: true });
+    writeFileSync(join(oldPath, 'celilo-backups', '2026-08-01', 'x.backup'), 'payload');
+
+    const storage = await addBackupStorage({
+      name: 'Movable Backups',
+      providerName: 'local',
+      credentials: { path: oldPath },
+    });
+
+    const result = await handleStorageSetPath([storage.storageId, newPath]);
+
+    expect(result.success).toBe(true);
+    expect(existsSync(join(newPath, 'celilo-backups', '2026-08-01', 'x.backup'))).toBe(true);
+    expect(existsSync(join(oldPath, 'celilo-backups'))).toBe(false);
+  });
+
+  test('preserves archive mtimes — a move does not restamp backups', async () => {
+    const oldPath = join(testRoot, 'mtime-old');
+    const newPath = join(testRoot, 'mtime-new');
+    const archive = join(oldPath, 'celilo-backups', 'a.backup');
+    mkdirSync(join(oldPath, 'celilo-backups'), { recursive: true });
+    writeFileSync(archive, 'payload');
+    const stamp = new Date('2026-04-26T01:37:53.740Z');
+    utimesSync(archive, stamp, stamp);
+
+    const storage = await addBackupStorage({
+      name: 'Mtime Backups',
+      providerName: 'local',
+      credentials: { path: oldPath },
+    });
+
+    await handleStorageSetPath([storage.storageId, newPath]);
+
+    const moved = statSync(join(newPath, 'celilo-backups', 'a.backup'));
+    expect(Math.round(moved.mtimeMs)).toBe(stamp.getTime());
+  });
+
+  test('--no-migrate leaves the old archives where they are', async () => {
+    const oldPath = join(testRoot, 'kept-old');
+    const newPath = join(testRoot, 'kept-new');
+    mkdirSync(join(oldPath, 'celilo-backups'), { recursive: true });
+    writeFileSync(join(oldPath, 'celilo-backups', 'y.backup'), 'payload');
+
+    const storage = await addBackupStorage({
+      name: 'Kept Backups',
+      providerName: 'local',
+      credentials: { path: oldPath },
+    });
+
+    const result = await handleStorageSetPath([storage.storageId, newPath], {
+      'no-migrate': true,
+    });
+
+    expect(result.success).toBe(true);
+    expect(existsSync(join(oldPath, 'celilo-backups', 'y.backup'))).toBe(true);
+    expect(existsSync(join(newPath, 'celilo-backups', 'y.backup'))).toBe(false);
+  });
+
+  test('handles a new path containing a space', async () => {
+    const oldPath = join(testRoot, 'spacey-old');
+    const newPath = join(testRoot, 'back ups', "Bob's celilo");
+    mkdirSync(join(oldPath, 'celilo-backups'), { recursive: true });
+    writeFileSync(join(oldPath, 'celilo-backups', 'z.backup'), 'payload');
+
+    const storage = await addBackupStorage({
+      name: 'Spacey Backups',
+      providerName: 'local',
+      credentials: { path: oldPath },
+    });
+
+    const result = await handleStorageSetPath([storage.storageId, newPath]);
+
+    expect(result.success).toBe(true);
+    expect(existsSync(join(newPath, 'celilo-backups', 'z.backup'))).toBe(true);
+  });
+
+  test('rejects an unknown storage id', async () => {
+    const result = await handleStorageSetPath(['no-such-storage', join(testRoot, 'x')]);
+    expect(result).toMatchObject({ success: false });
+  });
+
+  test('requires both a storage id and a path', async () => {
+    const result = await handleStorageSetPath(['only-one-arg']);
+    expect(result).toMatchObject({ success: false });
+  });
+});

package/src/cli/commands/storage-set-path.ts

@@ -0,0 +1,190 @@
+/**
+ * Storage Set Path Command
+ * Relocate a local storage destination to a new directory, migrating
+ * any archives that are actually there.
+ *
+ * Motivating case (#566): celilo-mgr's `local-backups` points at
+ * `/Users/pbanka/...`, a macOS path carried across when the database was
+ * restored onto a Linux host. The directory does not exist there, so the
+ * relocation must complete cleanly with nothing to migrate rather than
+ * erroring — and must not carry the old `✓ Verified` stamp onto the new
+ * path.
+ */
+
+import { cpSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  getBackupStorageByStorageId,
+  getStorageCredentials,
+  updateStorageCredentials,
+  verifyBackupStorage,
+} from '../../services/backup-storage';
+import { BACKUP_PREFIX } from '../../services/storage-providers/local';
+import { celiloIntro, celiloOutro } from '../prompts';
+import type { CommandResult } from '../types';
+import { probePathWriteable } from './storage-add-local';
+
+/** What the current archive directory turned out to be, on disk. */
+export type SourceState = 'missing' | 'unreadable' | 'empty' | 'populated';
+
+export interface RelocationPlan {
+  /** Whether to copy the source tree to the target. */
+  migrate: boolean;
+  /** One line for the operator explaining what will (not) happen. */
+  note: string;
+}
+
+/**
+ * Decide whether to migrate. Pure — takes an already-observed source
+ * state so it is testable without a filesystem (Rule 10.4).
+ */
+export function planRelocation(input: {
+  sourceState: SourceState;
+  sourceDir: string;
+  targetDir: string;
+  migrateRequested: boolean;
+}): RelocationPlan {
+  const { sourceState, sourceDir, targetDir, migrateRequested } = input;
+
+  if (!migrateRequested) {
+    return { migrate: false, note: `Migration skipped (--no-migrate). ${sourceDir} left as-is.` };
+  }
+
+  switch (sourceState) {
+    case 'missing':
+      return { migrate: false, note: `${sourceDir} does not exist — nothing to migrate.` };
+    case 'unreadable':
+      return { migrate: false, note: `${sourceDir} is not readable — nothing migrated.` };
+    case 'empty':
+      return { migrate: false, note: `${sourceDir} is empty — nothing to migrate.` };
+    case 'populated':
+      return { migrate: true, note: `Migrating archives from ${sourceDir} to ${targetDir}.` };
+  }
+}
+
+/**
+ * Validate and normalise the requested path. Pure apart from `~`
+ * expansion, which reads the environment but touches no filesystem.
+ */
+export function resolveTargetPath(
+  raw: string,
+  currentPath: string,
+): CommandResult | { path: string } {
+  const expanded = raw.startsWith('~/') || raw === '~' ? raw.replace('~', homedir()) : raw;
+  const resolved = resolve(expanded);
+
+  if (resolved === resolve(currentPath)) {
+    return { success: false, error: `Storage path is already '${resolved}' — nothing to do.` };
+  }
+
+  return { path: resolved };
+}
+
+/** Observe the archive directory. Distinguishes absent from unreadable. */
+export function inspectSourceDir(dir: string): SourceState {
+  try {
+    return readdirSync(dir).length === 0 ? 'empty' : 'populated';
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'missing' : 'unreadable';
+  }
+}
+
+export async function handleStorageSetPath(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    celiloIntro('Relocate Backup Storage');
+
+    const storageId = args[0];
+    const newPathArg = args[1];
+    if (!storageId || !newPathArg) {
+      return {
+        success: false,
+        error:
+          'Storage ID and new path are required\n\nUsage: celilo storage set-path <storage-id> <new-path> [--no-migrate]',
+      };
+    }
+
+    const storage = getBackupStorageByStorageId(storageId);
+    if (!storage) {
+      return { success: false, error: `Storage not found: ${storageId}` };
+    }
+    if (storage.providerName !== 'local') {
+      return {
+        success: false,
+        error: `'${storage.storageId}' is a ${storage.providerName} destination — set-path only applies to local storage.`,
+      };
+    }
+
+    const credentials = await getStorageCredentials(storage.id);
+    if (!('path' in credentials)) {
+      return { success: false, error: `Storage '${storage.storageId}' has no path configured.` };
+    }
+    const currentPath = credentials.path;
+
+    const resolved = resolveTargetPath(newPathArg, currentPath);
+    if ('success' in resolved) return resolved;
+    const newPath = resolved.path;
+
+    const writeError = probePathWriteable(newPath);
+    if (writeError !== null) {
+      return { success: false, error: `Path '${newPath}' is not writeable: ${writeError}` };
+    }
+
+    const sourceDir = join(currentPath, BACKUP_PREFIX);
+    const targetDir = join(newPath, BACKUP_PREFIX);
+    const plan = planRelocation({
+      sourceState: inspectSourceDir(sourceDir),
+      sourceDir,
+      targetDir,
+      migrateRequested: flags['no-migrate'] !== true,
+    });
+
+    console.log(`\n${plan.note}`);
+
+    if (plan.migrate) {
+      // A backup archive's mtime is part of what it is; a move must not
+      // restamp it. Bun's cpSync already preserves timestamps, so the
+      // flag is a no-op today — it is here for Node semantics, where the
+      // default is the other way. The mtime test guards the behavior,
+      // not this flag.
+      cpSync(sourceDir, targetDir, { recursive: true, force: true, preserveTimestamps: true });
+    }
+
+    await updateStorageCredentials(storage.id, { ...credentials, path: newPath });
+    console.log(`✓ Path updated: ${currentPath} → ${newPath}`);
+
+    if (plan.migrate) {
+      // Only after the DB points at the copy, so a failure here leaves
+      // archives duplicated rather than orphaned.
+      try {
+        rmSync(sourceDir, { recursive: true, force: true });
+      } catch (error) {
+        console.log(
+          `⚠ Copied, but could not remove ${sourceDir}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    const { result } = await verifyBackupStorage(storage.id);
+    if (!result.success) {
+      console.log(`✗ ${result.message}`);
+      celiloOutro(
+        `Path changed but verification failed.\n\nFix the path and re-verify: celilo storage verify ${storage.storageId}`,
+      );
+      return { success: false, error: result.message };
+    }
+
+    console.log(`✓ ${result.message}`);
+    celiloOutro(`'${storage.storageId}' now stores backups at ${targetDir}/`);
+
+    return { success: true, message: `Relocated ${storage.storageId} to ${newPath}` };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to set storage path: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

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

@@ -35,6 +35,7 @@ import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { decryptSecret } from '../../secrets/encryption';
 import { getOrCreateMasterKey } from '../../secrets/master-key';
+import { readAllTransportStatuses } from '../../services/alerting/read-records';
 import { runAudit } from '../../services/audit';
 import type { DriftFinding, SystemAuditReport } from '../../services/audit';
 import { loadBackupAuditInfo } from '../../services/audit/backup-source';
@@ -378,6 +379,17 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     secretsDecryptable: { results: secretResults },
     servicesReachable: { results: serviceReachableResults },
     machinesReachable: { results: machineReachableResults },
+    // Reads the record the poller already writes — this check never performs a
+    // read of its own. One that did would drain the queue and eat the
+    // acknowledgement it exists to protect (#541).
+    transportReads: {
+      statuses: readAllTransportStatuses(db),
+      now: new Date(),
+      // Six missed polls. The poller runs every five minutes, so this absorbs a
+      // slow sweep, a restart, and a missed tick without crying wolf — while
+      // still catching a transport that has genuinely stopped being readable.
+      staleAfterMs: 30 * 60_000,
+    },
     trustedSources: { firewalls: collectFirewallReach(db) },
   };
 }

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

@@ -585,6 +585,7 @@ export async function handleSystemUpdate(
     secretsDecryptable: { results: [] },
     servicesReachable: { results: [] },
     machinesReachable: { results: [] },
+    transportReads: { statuses: [], now: new Date(), staleAfterMs: 30 * 60_000 },
     trustedSources: { firewalls: [] },
   };
 

package/src/cli/completion.ts

@@ -486,7 +486,7 @@ export async function getCompletions(words: string[], current: number): Promise<
 
   // Storage subcommands
   if (command === 'storage' && currentIndex === 1) {
-    const subcommands = ['add', 'list', 'remove', 'verify', 'set-default'];
+    const subcommands = ['add', 'list', 'remove', 'verify', 'set-default', 'set-path'];
     return filterSuggestions(subcommands, args[1] || '');
   }
 
@@ -496,10 +496,13 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(providers, args[2] || '');
   }
 
-  // Storage remove/verify/set-default - complete with storage IDs
+  // Storage remove/verify/set-default/set-path - complete with storage IDs
   if (
     command === 'storage' &&
-    (args[1] === 'remove' || args[1] === 'verify' || args[1] === 'set-default') &&
+    (args[1] === 'remove' ||
+      args[1] === 'verify' ||
+      args[1] === 'set-default' ||
+      args[1] === 'set-path') &&
     currentIndex === 2
   ) {
     const storages = listBackupStorages();